Diagnose your setup

Use doctor, send-test-event, and queue diagnostics to verify your Ratri connection.

Something isn’t showing up in the dashboard. Before diving into code, run diagnostics to check config, registration, queue health, and event validation.

Doctor

TypeScript

npx ratri doctor
npx ratri doctor --send-test
npx ratri doctor --mcp --mcp-config ratri.mcp.json

doctor checks:

• Config file loaded correctly
• API key and base URL set
• Agent registration succeeded (agentId, agentVersionId)
• Queue is running and healthy
• Sample events pass validation

--send-test sends a single test event after checks. --mcp validates MCP proxy config and connectivity.

What you’ll see

Structured output with pass/fail for each check. On success, agent and workspace IDs are printed.

Send test event

End-to-end smoke test with session replay URL:

TypeScript

npx ratri send-test-event
npx ratri send-test-event --mode pipeline
npx ratri send-test-event --mode single
npx ratri send-test-event --mode proof

Mode	Simulates
pipeline (default)	Full session: orchestrator, LLM, workflow, tool, guard, handoff, child run
single	Minimal session with one tool call
proof	Activation proof: safe simulated session, risky production-like action, guardrail evaluation

What you’ll see

A session replay URL. Open it to verify the full pipeline appears in the dashboard.

SDK diagnostics

TypeScript

const report = await ratri.doctor();
const queue = ratri.queueDiagnostics();
const validation = await ratri.validateEvents([sampleEvent]);
const test = await ratri.sendTestEvent({ mode: "proof" });

Common issues

Symptom	Check
No events in dashboard	RATRI_API_KEY set? ready() called? flush() before exit?
Registration failed	RATRI_BASE_URL correct? API key valid?
Events rejected	Run validateEvents — check payload shapes
MCP proxy not intercepting	doctor --mcp — verify upstream command and config path
Queue growing	Network issues? Increase retryAttempts or check onError setting

Disabled mode

If enabled: false, all checks pass locally but nothing is sent to Ratri. Useful for CI without credentials.

Next steps

Connect your first agent

Initial setup walkthrough.

Errors reference

Error types and codes.