> ## Documentation Index
> Fetch the complete documentation index at: https://docs.calado.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common issues and how to fix them.

## 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:**

```ts theme={null}
await calado.flush();
console.log(calado.status());
```

`status()` returns:

```ts theme={null}
{
  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](/ingestion/node-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](/ingestion/serverless) 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:

```ts theme={null}
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](/ingestion/langfuse#troubleshooting) and [LangSmith](/ingestion/langsmith#troubleshooting) for the full setup and per-tracer troubleshooting.

## Still stuck?

Email [support@calado.ai](mailto: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