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

# Troubleshooting

> Diagnose missing TypeScript runs, steps, project assignment, and noisy logs.

<script src="/assets/sdk-nav.js" />

## Common checks

| Symptom                                            | Check                                                                                                        |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| No run appears                                     | Confirm the entrypoint reaches and awaits `sovara_client.run(...)`. Check the terminal for a Sovara warning. |
| Run appears in the wrong project                   | Check the `projectName` passed to `new SovaraClient(...)`.                                                   |
| An LLM or supported framework tool call is missing | Confirm the call executes and completes before the `run(...)` callback returns.                              |
| A custom operation is missing                      | Wrap its shared execution boundary with `trace`.                                                             |
| Claude Agent SDK calls are missing                 | Import `query` or `startup` from `@sovara/runner/claude`.                                                    |
| Logs mix between concurrent runs                   | Set `captureLogs: false` on concurrent top-level runs.                                                       |

## Keep recorded work inside the run

The run callback must contain and await the real agent task:

```ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
const sovara_client = new SovaraClient({ projectName: "support-agent" });

const answer = await sovara_client.run("answer question", async () => {
  return await runAgent(question);
});
```

Promises started without `await` may continue after the run has closed, so
their LLM and tool calls will not belong to that run. Use
`sovara_client.subrun(...)` when delegated work should appear as a child run.

## Trace custom operations

Supported provider, framework tool, and MCP calls are recorded automatically.
Use `trace` for important application operations that do not pass through one
of those integrations, such as retrieval, database access, parsing, or custom
tool dispatch:

```ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
const retrieveContext = trace(async function retrieveContext(question: string) {
  return vectorSearch(question);
});
```

Prefer one shared dispatch wrapper over many helper wrappers.

## Inspect what was recorded

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
sovara probe <run-id>
sovara probe <run-id> --step <step-ref> --preview
sovara logs <run-id> --tail 40
```

Use visible step refs from `probe`, not internal UUIDs.