> ## Documentation Index
> Fetch the complete documentation index at: https://docs.synheart.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors and environment

> Synheart CLI error codes, the environment variables it reads, and fixes for common problems.

When a command fails, the CLI prints a typed error. In JSON mode the same information is a JSON body with `error_code`, `class`, `exit_code` and `message`, plus `detail`, `hint`, `fix`, `did_you_mean` and `valid_values` when they apply, so scripts and agents can branch on it. See [Use the CLI from AI agents](https://docs.synheart.ai/cli/agents.md#errors-in-json).

```text theme={null}
✗ Not signed in   SH-AUTH-001
  No Synheart credentials found in the keyring or config file.

  TRY
    synheart login
```

Codes follow `SH-<DOMAIN>-<NUMBER>`. They are stable: search for them in your shell history, put them in support tickets, and branch on them in scripts. A code is never reassigned to a different meaning.

## Error codes

### Command line

| Code | Meaning | What to do |
| - | - | - |
| `SH-CLI-USAGE` | You called the CLI wrong: a bad flag or argument, an unknown command or subcommand (`did_you_mean` names the closest), or `--json` with a different `--format`. Also raised when you pass `--json` to a command with no JSON form, such as `guard allow`. Exit code 2. | Read the usage line the CLI prints (on stderr), or run the command with `--help`. |
| `SH-MOCK-NOTFOUND` | You named a mock scenario that does not exist. Exit code 4. | Run `synheart mock list-scenarios`. |
| `SH-EXPLAIN-NOTFOUND` | `synheart explain` has no primer for that topic. Exit code 4. | The error lists the topics, and the hint suggests the closest one. |
| `SH-MOCK-004` | `synheart mock start` could not bind: the port, port+1 or port+2 is already in use. A transient error, exit code 5, because the port frees up when the other process stops. The `fix` suggests another port. | Pass another `--port`, or stop whatever holds the port. |
| `SH-MOCK-005` | A mock stream is already running, or still shutting down, in this MCP server. A usage error, exit code 2. Only `synheart_mock_start` raises it. | Stop the running stream with `synheart_mock_stop`, or wait until `synheart_mock_status` says `stopped`. |
| `SH-MOCK-007` | `synheart_mock_stop` timed out: the stream is still shutting down and its ports may still be bound. A transient error, exit code 5. | Call `synheart_mock_status` until it says `stopped`, then start again. |
| `SH-MOCK-006` | The mock stream started through the MCP server did not bind its listeners in time. A transient error, exit code 5. | Call `synheart_mock_start` again, or pass another `port`. |
| `SH-MOCK-003` | The rate you typed is not valid. Seen when you change the rate on the interactive mock screen. | Use a frequency like `10hz` or an interval like `100ms`. |
| `SH-FLAG-REMOVED` | You passed a flag that no longer exists. Exit code 2. | The error names the flag and what replaces it. |
| `SH-AGENT-001` | The step is interactive, and [agent mode](https://docs.synheart.ai/cli/agents.md#agent-mode) never prompts. | Re-run with the flag in the hint, such as `--yes` or `--ci-token`. Set `SYNHEART_AGENT=0` if a person is running the command. |
| `SH-TUI-001` | `synheart ui` needs a terminal. It does not open in CI, in a pipe, or when `SYNHEART_NO_TUI=1` is set. | Use the ordinary commands, or run it from a terminal. |
| `SH-TUI-002` | `synheart ui` is off in agent mode. It is a usage error (exit 2) whose detail says how to open it yourself: set `SYNHEART_AGENT=0`. | Use the ordinary commands with `--json`, or `synheart help --json` for the command map. |

Any failure that is not a typed error has the code `SH-UNKNOWN` and exits 1. If you see one, the message is the underlying error text.

`synheart ui` with `--json`, `--format json` or `--quiet` fails with a plain error instead of a code: `TUI is not available with --format json` (or `--quiet`).

### Sign-in

| Code | Meaning | What to do |
| - | - | - |
| `SH-AUTH-001` | Not signed in. | `synheart login` |
| `SH-AUTH-002` | The CLI could not fetch your account info. | Retry. If it persists, run `synheart auth status`. |
| `SH-AUTH-003` | The credentials file is unreadable. | `synheart auth status` shows the path and permissions. |
| `SH-AUTH-004` | The CLI could not use the system keyring. | Unlock the OS keyring and retry, or set `SYNHEART_DISABLE_KEYRING`. |
| `SH-AUTH-005` | You denied the authorization in the browser. | Run `synheart login` again and approve it. |
| `SH-AUTH-006` | The device code expired before you finished. | Run `synheart login` again. |
| `SH-AUTH-007` | The CLI could not save your credentials locally. | Check the permissions of `~/.synheart`. |
| `SH-AUTH-008` | Authorization failed. | Run `synheart login` again. |
| `SH-AUTH-009` | The refresh token is expired or invalid. Retrying will not help. | `synheart login` |
| `SH-AUTH-010` | The CLI could not refresh your session, for a temporary reason. | Retry once. If it persists, run `synheart auth status`. |
| `SH-AUTH-011` | No CI token was supplied. | Set `SYNHEART_CI_TOKEN` or pass `--ci-token`. |
| `SH-AUTH-012` | The CLI could not save the CI token locally. | Check the permissions of `~/.synheart`. |
| `SH-AUTH-099` | Sign-in failed for another reason. | Run `synheart auth status`, then `synheart login` again. |

### Install, sync and runtime

| Code | Meaning | What to do |
| - | - | - |
| `SH-INST-001` | A package argument is missing, or there are too many. | `synheart install --help` |
| `SH-INST-002` | There is no `synheart.lock` in the project. | `synheart install runtime` |
| `SH-INST-003` | The CLI could not read the lockfile. | Check the file, or reinstall with `synheart install runtime`. |
| `SH-INST-004` | Lockfile drift: the lockfile names an artifact the current manifest no longer has. | Re-pin with the command in the hint, such as `synheart install runtime --version <version>`. |
| `SH-INST-005` | An artifact's SHA-256 does not match the lockfile. | Do not use the file. Re-pin with `synheart install`. |
| `SH-INST-PROJECT` | The CLI could not resolve the project directory. | Check `--project-dir`. |
| `SH-INST-VARIANT` | The variant is unknown, or `--variant` was used on something that is not a runtime. | Use `edge`, `stable` or `lab` with `install runtime`. |
| `SH-INST-FORBIDDEN` | Your account is not entitled to that runtime variant. | Install without `--variant`, or check your plan with `synheart usage`. |
| `SH-INST-EMPTY` | Nothing was installed. | Check that your plan includes the package. |
| `SH-RT-NOLOCK` | No runtime is installed in this app project. | `synheart install runtime` |
| `SH-RT-INCOMPATIBLE` | The installed runtime does not work with this project's `synheart_core` version. | Follow the hint, usually `synheart runtime upgrade`. |
| `SH-RT-FILES` | Runtime files are missing or modified compared with `synheart.lock`. | `synheart sync` |
| `SH-RT-SYMBOLS` | A runtime library lacks functions its variant must export. | Reinstall the variant: `synheart install runtime`. |

### Network and registry

| Code | Meaning | What to do |
| - | - | - |
| `SH-NET-001` | The CLI could not reach the auth service. | Check your connection and retry. |
| `SH-NET-002` | The CLI could not reach the release manifest. | Check your connection and retry. |
| `SH-NET-003` | The CLI could not reach the artifact registry, or a download failed. | Check your connection and retry. |
| `SH-NET-004` | The CLI could not reach the platform API, or it did not answer in time. Exit code 5, so it is safe to retry. | Check your connection and `SYNHEART_API_URL`, then retry. `synheart doctor` checks connectivity. |
| `SH-REG-404` | The interactive install screen could not find the package. | Try the latest channel, and set a platform if the package is platform-specific. |
| `SH-REG-429` | The registry is rate limiting the interactive install screen. | Wait a moment and try again. |
| `SH-REG-000` | The interactive install screen hit another registry error. | Retry. The message carries the registry's reason. |
| `SH-SUPPLY-001` | This CLI build does not trust the registry signing key. | Update the CLI: `synheart update`. |
| `SH-SUPPLY-002` | The registry manifest is not signed. | Do not continue. Contact support. |
| `SH-SUPPLY-003` | The registry manifest signature is invalid, or could not be verified. | Do not continue. Contact support. |
| `SH-SUPPLY-004` | The registry manifest is outside its validity window. | Check your system clock, then retry. |
| `SH-PLATFORM-400` | The platform rejected the request. | Check the arguments. |
| `SH-PLATFORM-403` | Forbidden. Exit code 3. | Check `--org`, `--tenant`, or `SYNHEART_ORG_ID`. |
| `SH-PLATFORM-404` | Not found. | `synheart org list` to confirm the resource exists. |
| `SH-PLATFORM-429` | The platform is rate limiting you. Exit code 5. | Wait a moment and retry. |
| `SH-PLATFORM-500` | The platform service had an error. | Retry later, or contact support. |

The `synheart org`, `project` and `api-key` commands return `SH-AUTH-001` for an HTTP 401.

### Agents: guard, Life and Synapse

Some commands change what your coding agents are allowed to do or what they send. They run only when you type them in a terminal of your own, so an agent can't run them for itself. Claude Code's `!` prefix runs a command in the agent's shell, so it counts as the agent too.

| Code | Meaning | What to do |
| - | - | - |
| `SH-GUARD-HUMAN` | A guard command that changes enforcement (`guard install --write`, `guard init`, `guard rules add`, `guard allow`, `guard team join`, `leave` or `decisions`) ran from an agent's shell. | Run it in a terminal window of your own, outside your agent. |
| `SH-LIFE-HUMAN` | `synheart life connect --write` or `disconnect --write` ran from an agent's shell. | Run it in a terminal window of your own. |
| `SH-TELEMETRY-001` | `synheart synapse telemetry on` ran from an agent's shell. Sending telemetry is your choice, even with `SYNHEART_AGENT=0`. | Run it in a terminal window of your own. |
| `SH-TELEMETRY-002` | Synapse couldn't create the telemetry credential. | Your organization needs Synapse, and your role must allow creating your own MCP tokens. |
| `SH-TELEMETRY-003` | The Synapse address the CLI would send telemetry to isn't `https`. | Point the CLI at an `https` address, or remove your override. |
| `SH-TELEMETRY-004` | Your Claude Code settings already send telemetry somewhere else. Nothing was changed. | Remove the keys the error names from your settings if Synapse should receive it, then retry. |
| `SH-TELEMETRY-005` | Synapse didn't grant the telemetry scope. | Ask an organization admin, then retry. |
| `SH-TELEMETRY-006` | Another telemetry helper is refreshing the credential. | Retry in a minute. |

### Config, update, usage and Syni

| Code | Meaning | What to do |
| - | - | - |
| `SH-CFG-002` | No project config was found. | Run `synheart init`, or create `.synheart/config.yaml`. See [project settings](https://docs.synheart.ai/cli/overview.md#settings-precedence). |
| `SH-CFG-003` | The theme name is unknown. The error names where it was set, and the JSON body has `did_you_mean` and `valid_values`. | Use `tide`, `ember`, `signal` or `mono`. |
| `SH-CFG-004` | `SYNHEART_THEME_MODE` (or `ui.mode`) is not `auto`, `light` or `dark`. The JSON body has `valid_values`, and `did_you_mean` when the value is close to one. | Set it to `auto`, `light` or `dark`, or unset it. |
| `SH-CFG-005` | `synheart init` could not run: there is no directory at the path you gave, or it could not write `.synheart/config.yaml`. | Check `--project-dir` and that you can write to the directory. |
| `SH-CFG-007` | `synheart init` won't write through a symlink: `.synheart`, `.synheart/config.yaml` or a backup path is a symbolic link. A usage error, exit code 2. | Replace the link with a real directory or file, then run `synheart init` again. |
| `SH-CFG-006` | `synheart init` ran in your home directory. `~/.synheart/config.yaml` holds your personal settings, so init refuses to touch it. A usage error, exit code 2. | `cd` into your app, then run `synheart init` again, or pass `--project-dir <your app directory>`. |
| `SH-CFG-HOME` | The CLI could not find your home directory. | Set `HOME` (or `USERPROFILE` on Windows). |
| `SH-LOCAL-ADMIN` | On Windows, the interactive local platform screen needs Administrator rights to edit the hosts file for HTTPS mode. | Reopen the terminal with Run as administrator and try again. |
| `SH-LOCAL-SUDO` | The interactive local platform screen needs administrator rights, and `sudo` cannot prompt inside the full-screen UI. | Quit the UI (`q`) and run the command from a shell, or run `sudo -v` first and try again. |
| `SH-UPD-MANAGED` | A package manager manages this binary. | Update with the package manager, or pass `--force`. |
| `SH-UPD-APPLY` | The update failed to apply. The existing binary is untouched. | Retry. |
| `SH-UPD-ROLLBACK` | The rollback failed. | Reinstall with the installer script. |
| `SH-UPD-NOPREV` | There is no previous binary to roll back to. | Nothing to do. |
| `SH-UPD-NOPLATFORM` | The latest manifest has no binary for your OS and architecture. | Check the release page. |
| `SH-UPD-EXEC` | The CLI could not find its own binary path. | Reinstall with the installer script. |
| `SH-UPD-ABORT` | You declined the update prompt. | Run `synheart update --yes` to skip the prompt. |
| `SH-USAGE-001` | There is no organization on this session. | Pass `--org`, or set `SYNHEART_ORG_ID`. |
| `SH-USAGE-002` | The billing API request failed. | Retry later. |
| `SH-USAGE-403` | You are not allowed to read usage for this org. Exit code 3. | Check your role. |
| `SH-USAGE-404` | The usage endpoint was not found. | Check `--org`. |
| `SH-SYNI-001` | A Syni message is required. | Pass a message to `synheart syni chat`. |
| `SH-SYNI-002` | A project ID is required to list personas. | Pass `--project`, set `SYNHEART_PROJECT_ID`, or add `project:` under `platform:` in `.synheart/config.yaml`. `synheart project list` shows the ids. |
| `SH-SYNI-403` | Syni cloud chat is not allowed for this org. Exit code 3. | Check your plan. |
| `SH-SYNI-404` | The persona or session does not exist. Exit code 4. | `synheart syni personas`, and check the `--session` ID. |
| `SH-SYNI-429` | You are over your Syni quota. | Wait, or check `synheart usage`. |
| `SH-SYNI-500` | The Syni API request failed. | Retry later. |

## Environment variables

The CLI reads these variables. Each is checked against the CLI source.

| Variable | Purpose |
| - | - |
| `SYNHEART_AGENT` | `1` forces [agent mode](https://docs.synheart.ai/cli/agents.md#agent-mode) on. `0` forces it off. |
| `CLAUDECODE`, `CLAUDE_CODE_ENTRYPOINT`, `CURSOR_AGENT`, `CODEX_SANDBOX`, `GEMINI_CLI`, `COPILOT_AGENT` | Set by coding agents. Any of them turns agent mode on. |
| `SYNHEART_NO_TUI` | `1` stops the interactive UI from opening. |
| `SYNHEART_MOUSE` | `0` leaves the mouse to your terminal: plain click-drag selects text, but the wheel scrolls the terminal instead of the interactive UI. |
| `SYNHEART_NO_UPDATE_CHECK` | `1` turns off the passive update notice. |
| `SYNHEART_THEME` | Colour theme: `tide`, `ember`, `signal` or `mono`. Same as `--theme`. |
| `SYNHEART_THEME_MODE` | `auto` (the default), `light` or `dark`. `light` and `dark` skip the terminal background check. |
| `SYNHEART_REDUCED_MOTION` | A truthy value, such as `1`, turns off animation. |
| `SYNHEART_API_URL` | Overrides the platform API base URL. The default is `https://api.synheart.ai`. |
| `SYNHEART_DIST_URL` | Overrides the distribution URL. The default is `https://dist.synheart.ai`. |
| `SYNHEART_UPDATE_MANIFEST_URL` | Overrides the manifest URL that `synheart update` reads. |
| `SYNHEART_CI_TOKEN` | A long-lived token for non-interactive `synheart login`. Prefer it over `--ci-token`, because flags show up in process lists and shell history. |
| `SYNHEART_DISABLE_KEYRING` | Stores credentials in `~/.synheart/credentials.enc` instead of the system keyring. |
| `SYNHEART_ORG_ID` | Default organization ID for `usage`, `syni`, and the `org`, `project` and `api-key` commands. |
| `SYNHEART_TENANT_ID` | Default tenant ID for `syni` and the platform commands. |
| `SYNHEART_PROJECT_ID` | Default project ID for `syni`. Overrides `platform.project` in `.synheart/config.yaml`. |
| `SYNHEART_INSTALL_JOBS` | Number of parallel downloads for `install` and `sync`, from 1 to 16. |
| `SYNHEART_ALLOW_ALL_ORIGINS` | `1` lets the mock servers accept browser requests from any origin. By default only non-browser clients, `file://` pages and loopback origins are accepted. |
| `SYNHEART_INSTALL_DIR` | Read by the installer scripts, not by the CLI. Sets where `synheart` is installed. |
| `NO_COLOR` | Any value turns off colour. See [no-color.org](https://no-color.org). |
| `CI` | Any value turns off the interactive UI and update notices. |

Two further variables, `SYNHEART_INSECURE_SKIP_MANIFEST_VERIFY` and `SYNHEART_REGISTRY_PINNED_KEYS_FILE`, exist only for CLI developers testing against an unsigned or local registry. Never set them in a real environment.

## Troubleshooting

> [accordion] Install or sync asks me to sign in
>
> Run `synheart login`. Artifact commands need a valid session. If you keep getting sent back to login, run `synheart auth status` to see where the CLI loads credentials from and when they expire. Then `synheart logout` and `synheart login` again.

> [accordion] Sign-in does not work in CI or in an agent
>
> The browser flow needs a person. Create a CI token in the dashboard, set `SYNHEART_CI_TOKEN`, and run `synheart login`.

> [accordion] Mock stream port already in use
>
> Pass `--port` to `synheart mock start`, or check a port with `synheart doctor --port 8787`. The defaults are 8787 (WebSocket), 8788 (SSE) and 8789 (UDP). `--port N` moves all three together: WebSocket on N, SSE on N+1, UDP on N+2. If any of the three is taken, the command fails with `SH-MOCK-004` (exit 5).

> [accordion] I need the same runtime version in CI
>
> Commit `synheart.lock`, and run `synheart sync` in CI. If the lockfile no longer matches the registry, `sync` fails with `SH-INST-004` or `SH-INST-005` instead of installing something different. `synheart doctor` also reports modified runtime files (`SH-RT-FILES`).

> [accordion] synheart local --https fails to write /etc/hosts
>
> The HTTPS mode adds an `/etc/hosts` entry and trusts a local certificate, which can need administrator rights. Run it with the permissions the error asks for, or use plain HTTP (`synheart local`). Undo the changes with `synheart local cleanup --remove-certs`.

> [accordion] The receiver cannot be reached from my phone
>
> Check that your phone and computer are on the same network, and that your firewall allows the receiver's port (default 8787). The receiver listens on every interface unless you pass `--host`. `synheart doctor --port 8787` checks that the port is free.

> [accordion] SYNHEART\_API\_URL is not picked up
>
> The CLI reads environment variables on every run. Check that the variable is exported in the shell that runs the CLI, and run `synheart env` to confirm.

> [accordion] The colours look wrong on my terminal
>
> Set `SYNHEART_THEME_MODE=light` or `dark` if the CLI guessed your background wrongly. Pick another theme with `--theme`, or turn colour off with `NO_COLOR=1`.

For anything else, run `synheart doctor`, and include the output of `synheart version --build` when you ask for help.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.