Troubleshooting

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:

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:

const retrieveContext = trace(async function retrieveContext(question: string) {
  return vectorSearch(question);
});

Prefer one shared dispatch wrapper over many helper wrappers.

Inspect what was recorded

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.

Get started

Use the SDK

Reference

Troubleshooting

Common checks

Keep recorded work inside the run

Trace custom operations

Inspect what was recorded

​Common checks

​Keep recorded work inside the run

​Trace custom operations

​Inspect what was recorded

Common checks

Keep recorded work inside the run

Trace custom operations

Inspect what was recorded