> ## 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`, `title`, `error`, `detail` and `hint`, so scripts and agents can branch on it. See [Use the CLI from AI agents](/cli/agents#errors-in-json).

```text theme={null}
✗ Not logged 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 `--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-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](/cli/agents#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. | Use the ordinary commands with `--json`, or `synheart help --json` for the command map. |

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

### Config, update, usage and Syni

| Code | Meaning | What to do |
| - | - | - |
| `SH-CFG-002` | No project config was found. | Create `.synheart/config.yaml`. See [project settings](/cli/overview#settings-precedence). |
| `SH-CFG-003` | The theme name is unknown. The error names where it was set. | Use `tide`, `ember`, `signal` or `mono`. |
| `SH-CFG-004` | `SYNHEART_THEME_MODE` (or `ui.mode`) is not `auto`, `light` or `dark`. | Set it to `auto`, `light` or `dark`, or unset it. |
| `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](/cli/agents#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` | `1` lets the interactive UI capture the mouse for wheel scrolling. |
| `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

<AccordionGroup>
  <Accordion title="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>

  <Accordion title="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>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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>

  <Accordion title="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>

  <Accordion title="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>

  <Accordion title="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>

  <Accordion title="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`.
  </Accordion>
</AccordionGroup>

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.