Skip to main content

​
sovara: command not found

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

​
A command reports an incompatible server

The CLI and the server it reached implement different versions of a wire contract, so the command stops before sending the request:
The message names both sides. Update whichever one is behind, or select a server that shares a version. Nothing was changed on the server, because the check runs before the request reaches a handler. An older component that predates compatibility checks is not affected. It sends no version metadata, is treated as legacy, and keeps working.

​
Sovara is not reachable

Check the currently configured app environment:
Open the desktop app and verify the active app-server connection in the selector on the Projects page. With Local selected, keep the app open so its bundled backend is available. For a remembered remote connection, verify its origin under Settings > App-server connection settings and sign in through the app. CLI app commands automatically use the selected desktop app-server connection and, when it is remote, its session. For headless agent hosts, configure the exec-server URL and agent token directly in the Python or TypeScript SDK. That configuration applies to recording and runtime traffic, not user-facing CLI app commands.

​
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:
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. A new name selects or creates a different project. Renaming a project in the Sovara app does not update deployed SDK clients: until this value is changed they stop recording to that project. Rename first, then update clients. A client that sends the new name before the rename creates a project under it, and the rename then fails because the name is taken.

​
A module is missing during record

Use the same environment that normally runs the application:

​
A project-scoped command requires --project-id

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

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

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