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

> Fix common Sovara CLI setup, reporting, inspection, and rerun issues.

## `sovara: command not found`

Open a new terminal after installing the CLI so the shell reloads `PATH`. If it
still fails, reinstall and verify:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -fsSL https://apps.sovara-labs.com/cli/install.sh | sh
sovara --version
```

## Sovara is not reachable

Check the currently configured app environment:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
sovara status
```

For a local desktop environment, open the desktop app and retry. For remote
deployments, set `SOVARA_APP_SERVER_URL` for app commands. Configure the exec
server URL and agent token directly in the Python or TypeScript SDK for
headless agent hosts.

## `record` says no SDK-created run was observed

The child command ran, but it did not complete an SDK top-level run. Confirm
that the executed path reaches:

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from sovara import SovaraClient

sovara_client = SovaraClient(project_name="support-agent")
with sovara_client.run("answer-question"):
    run_agent()
```

`record` does not add this boundary automatically.

## A run appears in the wrong project

Change the project name in the SDK integration:

* Python: `SovaraClient(project_name="...")`
* TypeScript: `new SovaraClient({ projectName: "..." })`

The current directory and `record` command do not select a project. Project
names are immutable; a new name selects or creates a different project.

## A module is missing during `record`

Use the same environment that normally runs the application:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
sovara record -- /path/to/venv/bin/python agent.py
```

## A project-scoped command requires `--project-id`

List accessible projects, then pass a full ID, unambiguous ID prefix, or exact
project name:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
sovara projects
sovara annotations list --project-id support-agent --status queue
sovara lessons list --project-id support-agent
```

## `rerun` says the replay API key is not configured

Set a replay key for the provider shown in the error, then retry. See [Replay
Keys](/cli/replay-keys).

## `rerun` says the step is not replayable

Only recorded LLM calls can be rerun. Inspect tool calls and custom traced
functions with `probe`, then rerun the complete application normally.

## Restricted shell or sandbox writes fail

Allow writes to the global Sovara state directory, or install the assistant
skill so it can configure that access. For Python package caches, use writable
temporary locations when necessary:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
export UV_CACHE_DIR=/tmp/uv-cache
export PYTHONPYCACHEPREFIX=/tmp/pycache
```