Troubleshooting

Common checks

Symptom	Check
No run appears	Confirm the entrypoint enters `sovara_client.run(...)`. Check the terminal for a Sovara warning.
Run appears in the wrong project	Check the `project_name` passed to `SovaraClient(...)`.
An LLM or supported framework tool call is missing	Confirm the call executes before the `run(...)` context exits.
A custom operation is missing	Wrap its shared execution boundary with `trace`.
Threaded work attaches to the wrong run	Submit `sovara_client.with_context(fn)` to the executor.
Logs mix between concurrent runs	Set `capture_logs=False` on concurrent top-level runs.

Check the installed SDK

Confirm the interpreter that runs the agent can import the public API:

python -c "from sovara import SovaraClient, trace; print('ok')"
python -c "import sys; print(sys.executable)"

Keep recorded work inside the run

The run context must contain the real agent task:

sovara_client = SovaraClient(project_name="support-agent")

with sovara_client.run("answer question"):
    answer = run_agent(question)

For async agent code, use async with and await the task before leaving the context. Work moved to another thread needs sovara_client.with_context(...) so it retains the active 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:

from sovara import trace

@trace
def retrieve_context(question: str) -> list[str]:
    return vector_search(question)

Prefer one shared dispatch wrapper over many helper decorators.

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

Check the installed SDK

Keep recorded work inside the run

Trace custom operations

Inspect what was recorded

​Common checks

​Check the installed SDK

​Keep recorded work inside the run

​Trace custom operations

​Inspect what was recorded

Common checks

Check the installed SDK

Keep recorded work inside the run

Trace custom operations

Inspect what was recorded