Troubleshooting

Common checks

Symptom	Check
No trace appears	Confirm the entrypoint reaches and awaits `sovara_client.trace(...)`. Check the terminal for a Sovara warning.
An evaluation sample is missing from Traces	Look in Evaluations; the main Traces view excludes evaluation-owned samples.
Lessons are missing	Check that the proposal was applied, automatic injection is enabled, required models are configured, and the lesson scope includes the right folders.
Trace 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 `trace(...)` 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 traces	Set `captureLogs: false` on concurrent top-level traces.

Recording is unavailable

For local recording, install the CLI. For a remote server, set url and agentToken (or SOVARA_AGENT_TOKEN); see the API reference. An unreachable server may let your agent continue without recording. getTraceId() returns undefined in that case, and logging helpers do nothing. During recording, await logging calls and handle any errors. Authentication and version mismatches raise; update the component named in the error.

Missing custom steps

Import @sovara/runner before creating clients or capturing a reference to fetch. Add trace only to operations that are not already recorded:

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

For Claude Agent SDK calls, use the Claude wrapper.

Inspect what was recorded

sovara probe <trace-id>
sovara probe <trace-id> --step <step-ref> --preview
sovara logs <trace-id> --tail 40

Use step references shown by probe.

Traces and turns

Keep agent work inside trace() and await tasks and streams before the callback returns. Declare conversation turns with turn(); they are not created automatically. Do not nest turns in the same trace or use a different client inside it. See the usage guide.

Get started

Use the SDK

Reference

Troubleshooting

Common checks

Recording is unavailable

Missing custom steps

Inspect what was recorded

Traces and turns

​Common checks

​Recording is unavailable

​Missing custom steps

​Inspect what was recorded

​Traces and turns

Common checks

Recording is unavailable

Missing custom steps

Inspect what was recorded

Traces and turns