> ## 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 Python runs, steps, project assignment, and context.

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

## 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:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

```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.