Troubleshooting - Sovara

Common checks

Symptom	Check
No trace appears	Confirm the entrypoint enters `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 `project_name` passed to `SovaraClient(...)`.
An LLM or supported framework tool call is missing	Confirm the call executes before the `trace(...)` context exits.
A custom operation is missing	Wrap its shared execution boundary with `trace`.
Threaded work attaches to the wrong trace	Submit `sovara_client.with_context(fn)` to the executor.
Logs mix between concurrent traces	Set `capture_logs=False` on concurrent top-level traces.

Recording is unavailable

For local recording, install the CLI. For a remote server, set base_url and pass agent_token explicitly; see the API reference. An unreachable server may let your agent continue without recording. Check the trace ID before logging:

with sovara_client.trace("answer-question") as trace_id:
    answer = run_agent(question)
    if trace_id is not None:
        sovara_client.log(trace_id=trace_id, trace_output=answer)

log() and create_eval_run() raise on errors. Authentication and version mismatches also raise; update the component named in the error.

Missing custom steps

Import Sovara before creating provider clients and tools. Use openai-agents>=0.13,<1 for OpenAI Agents function-tool capture. Add @trace only to operations that are not already recorded:

from sovara import trace

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

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 leaving it. Use with_context() when passing work to another thread. 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.