Skip to main content

​
My data isn’t showing up in the dashboard

calado batches events in memory and only sends them when either the batch size or the flush interval is reached. In low-traffic or serverless setups, data can sit in the queue longer than you expect. Try this first: 
await calado.flush();
console.log(calado.status());
status() returns: 
{
  enabled: boolean;
  queued: number;
  lastIngestAt: Date | null;
  lastError: Error | null;
  consecutive401s: number;
}
  • queued > 0 and lastIngestAt is null → transport hasn’t sent yet. Call flush().
  • lastError is set → inspect it. Often a 4xx from a malformed payload.
  • enabled: false → transport is disabled. See the 401 section below.

​
I’m getting 401 errors

calado auto-disables the transport after three consecutive 401 responses to stop filling your logs with noise. Fix:
  1. Check your API key. It must start with cl_ and match an agent you own.
  2. Confirm CALADO_API_KEY is actually populated in the runtime environment. In serverless setups, env vars don’t always inherit the way you expect.
  3. Re-run calado.init(process.env.CALADO_API_KEY!) with the corrected key. This resets the disabled state.

​
status().enabled is false and I haven’t changed anything

Three consecutive 401s in a row will flip it. Check consecutive401s on the status output to confirm. Re-initialize with a valid key to recover. There’s no other way to re-enable.

​
Conversations are showing up, but they’re all single-turn

You’re missing conversation context. Each call to your wrapped client is one turn. Without grouping, calado can’t tell that multiple turns belong together. See Node.js SDK → Conversation tracking for the fix.

​
Dashboard is empty after a fresh ingest

Raw conversations appear in the dashboard immediately after ingest, but analysis doesn’t start automatically. Calado only runs classification when you click Run Analysis on the agent page.
  1. Open your agent in the dashboard and confirm your conversations are listed (they’ll show as pending classification).
  2. Click Run Analysis on the agent page to start Stage 0 / Stage 1 classification.
  3. Analysis runs in the background and takes minutes, not seconds. Findings appear once there’s enough data to group.
Open the agent’s Analysis runs section to see run status. If the latest run is pending or running, wait. If it’s failed, the error detail is on the run page. Re-run analysis after ingesting new conversations or editing agent definitions to re-classify.

​
Wrapping doesn’t return a proxy

calado.wrap(client) detects Anthropic and OpenAI clients by looking for client.messages.create (Anthropic) or client.chat.completions.create (OpenAI). If your client doesn’t match, wrap returns the client unchanged and calado never captures its calls. Common causes:
  • The client was instantiated before calado.init(). calado’s wrap uses the state set up by init; call them in order.
  • You’re using a library that wraps Anthropic or OpenAI but exposes a different surface. In that case, call the underlying Anthropic or OpenAI client directly and wrap that.

​
Everything works locally but not in production

In serverless runtimes, the 5-second flush timer often doesn’t fire before the function freezes. Your events get stranded in a queue that dies with the function. See Serverless patterns for the fix. Short version: call await calado.flush() (or hand it to waitUntil / after) before your handler returns.

​
I need to fully disable calado in tests

Don’t call calado.init() in your test environment. The SDK’s wrap() returns the client unchanged when the SDK hasn’t been initialized, so your LLM calls keep working and nothing is sent anywhere. For explicit teardown after initialization: 
await calado.shutdown();

​
My Langfuse or LangSmith webhook isn’t delivering anything

The most common cause is a missing trigger. A webhook URL alone never fires. Langfuse needs a trigger on Trace finished; LangSmith needs an Automation rule that matches your runs. Both default to firing on nothing. If the webhook does fire but calado rejects it:
  • 401 — the bearer token was rejected. Re-paste your cl_ key into the tracer’s webhook header. The usual cause is a stray space or a missing Bearer prefix.
  • 400 too_many_child_runs — one trace exceeded the per-trace cap (950 observations for Langfuse, 950 runs per trace_id for LangSmith). Reduce trace verbosity or split long work into shorter sessions.
See Langfuse and LangSmith for the full setup and per-tracer troubleshooting.

​
Still stuck?

Email support@calado.ai with:
  • The output of calado.status()
  • Your SDK version (npm ls calado)
  • The runtime (Node version, Vercel / Lambda / bare metal)
  • A minimal reproduction if possible