---
title: Troubleshooting
description: Diagnose a venom setup with venom doctor and fix the common install, endpoint, key, model, sandbox and trust problems.
section: getting-started
order: 90
audience: [user, operator, agent]
sources: [cli/src/doctor.ts, cli/src/doctor-lib.ts, cli/src/doctor-fix.ts, cli/src/node-check.ts, docs/getting-started.md]
features: []
---

Start with `venom doctor`. It checks the whole setup in a few seconds and prints one line per check, `PASS`, `WARN` or `FAIL`, each failure with its fix. The exit code is 1 when a required check fails.

```bash
venom doctor            # every section
venom doctor --probe    # also a short chat and a tool call to the model (costs one request)
venom doctor --fix      # then offers a fix for each problem it can repair, asking first
```

## venom doctor {#doctor}

| Flag | What it does |
|---|---|
| `--only <sections>` | Run only these sections, comma-separated: `policy`, `environment`, `cloud`, `orchestrator`, `probe`, `browser`, `sandbox`, `project`, `sovereignty`. Only their failures set the exit code, and the report names the scope. |
| `--probe` | Also send the model two tiny requests: a chat (time to first token) and a structured tool call. With `--only`, include `probe` in the list. |
| `--model <id>` | The model to probe. Default: `VENOM_MODEL`, then the saved `defaultModel`, then `venom-default`. |
| `--json` | The same report as JSON, with a `scope` field, for scripts. |
| `--fix` | After the report, walk through a fix for each check venom can repair (link `venom` onto your PATH, write a starter config, sign in to Venom Cloud again), asking before each. Steps it can't take are printed as commands. |
| `--yes`, `-y` | With `--fix`: apply every fix without asking. |
| `--check-update` | Also compare your version with the latest release (one request to GitHub). |

What each section checks:

| Section | Checks |
|---|---|
| `policy` | The organisation policy in force, where it came from, and who to ask about it |
| `environment` | Node version, venom's state directories, the install and PATH |
| `cloud` | The Venom Cloud login (`venom cloud login`) and its key |
| `orchestrator` | The endpoint is reachable, the key is accepted, the models and their context windows, upstream health and missing route models (when `VENOM_ADMIN_TOKEN` lets it read them) |
| `probe` | With `--probe`: a chat and a tool call |
| `browser` | Which Chrome, Edge, Chromium or Brave `--chrome` would use, and whether the default model takes images |
| `sandbox` | The OS sandbox (`sandbox-exec` on macOS, `bwrap` on Linux) and that it can run a command |
| `project` | What the current project loads: trust state, memory files, skills, commands, subagents, MCP servers, permission rules, hooks, plugins, language servers, config warnings |
| `sovereignty` | That venom makes no startup calls (`PI_OFFLINE`), and where your prompts go: this machine, your own servers, or a cloud provider |

For live diagnostics in a session, start venom with `VENOM_DEBUG=1`: it prints the harness's notes on hooks, compaction and MCP servers as they happen.

## Common problems {#problems}

### Install and start {#install}

| Symptom | Cause | Fix |
|---|---|---|
| `venom: command not found` | `~/.venom/bin` is not on your PATH | Add `export PATH="$HOME/.venom/bin:$PATH"` to your shell profile ([Install](/docs/getting-started/install.md#path)) |
| `the Linux builds need glibc` from the installer | Alpine or another musl system | Use a glibc distribution, a glibc container, or build from source |
| `checksum mismatch … nothing was installed` | The download was cut or altered | Run the installer again; if it repeats, download by hand and compare with `SHA256SUMS` |
| `venom needs Node.js >=22.19.0` | A source install running on an older Node (release archives bring their own) | Install Node 24 (`nvm install 24`, `fnm install 24`) |
| `make link-cli` fails with `EACCES` (devbox or a Nix shell) | npm's global prefix is read-only | `venom doctor --fix` links `venom` into a writable directory on your PATH |

### Endpoint and key {#endpoint}

| Symptom | Cause | Fix |
|---|---|---|
| `FAIL reachable … connection refused` | Nothing listens at `VENOM_BASE_URL`; the default is an orchestrator on `localhost:8787` | Start the orchestrator, Ollama or the daemon, or set `VENOM_BASE_URL` to the endpoint you use ([Local or cloud](/docs/getting-started/local-or-cloud.md)) |
| `FAIL auth … 401`, or a 401 in a session | `VENOM_API_KEY` is missing or not a key the endpoint accepts | Export the right key. Venom Cloud keys start with `vck_`; for a source install, export the `VENOM_API_KEY` from `.env`; for the daemon, `client_key` in its `secrets.json` |
| The endpoint check fails on Venom Cloud | `VENOM_BASE_URL` is missing `/v1` or has a trailing slash | Use `https://cloud.usevenom.dev/v1` |
| `FAIL health … /readyz HTTP 503: no healthy upstream` | The orchestrator has no reachable model: Ollama is not running, no cloud key | Start Ollama and pull a model, or give the orchestrator a provider key and restart it |
| `bind: address already in use` in the orchestrator's log | Another process (often a second orchestrator) holds `127.0.0.1:8787` | Stop it, or start this one with `VENOM_LISTEN=127.0.0.1:8788` and export `VENOM_BASE_URL=http://localhost:8788/v1` |
| `lists no venom-* aliases … set VENOM_ALIAS_MAP` | A plain OpenAI-compatible server with many models, or ids venom can't rank | Set `VENOM_MODEL` and `VENOM_ALIAS_MAP=venom-fast=<id>,venom-smart=<id>` |

### Models {#models}

| Symptom | Cause | Fix |
|---|---|---|
| A model you didn't expect | `--model` and `VENOM_MODEL` win over the model `/model` saved; a reopened session keeps its own model | `venom doctor` names the model in use and warns about a saved one the server doesn't list |
| The model answers in prose instead of calling tools | The local model doesn't emit structured tool calls | Confirm with `venom doctor --probe`; switch to a qwen3-family model |
| A gear is listed as unavailable | The endpoint serves none of its models, or the orchestrator lacks its route profile | `/gear` says which; pick another gear or build one with `venom gear new` ([Your first gear](/docs/getting-started/first-gear.md)) |
| Long sessions forget the start, or the local model ignores instructions | Ollama truncated a prompt longer than its context length | Start Ollama with a larger `OLLAMA_CONTEXT_LENGTH` and set `VENOM_CONTEXT_WINDOW` to match |
| `400 images_not_supported` | The session's model takes no images | Use a vision model, or set a vision model for text-only sessions |
| A session cost more than expected | Long turns, prompt-cache churn, large tool outputs or subagents | `venom explain-cost` (or `/explain-cost`) shows turn by turn where it went |

### Spend limits and policy {#limits}

| Symptom | Cause | Fix |
|---|---|---|
| `429 budget_exceeded` | The key's hard daily or monthly budget is used up | Wait for the reset named in the error (and the `x-venom-budget-reset` header), ask an admin to raise it, or use a local model |
| `403 unpriced_model` | A key with a hard budget asked for a cloud model with no known price | Use a priced or local model, or have the operator add a price |
| `… is not allowed by the organisation policy` (exit 2) | Your organisation's policy forbids that mode, flag, browser or endpoint | Use what it allows; `venom doctor` lists the policy and who to ask |

### Sandbox and trust {#sandbox}

| Symptom | Cause | Fix |
|---|---|---|
| Bash asks in yolo mode, or venom says there is no OS sandbox | `bwrap` is missing on Linux; Windows has no sandbox | Linux: install `bubblewrap` ([Install](/docs/getting-started/install.md#bubblewrap)); Windows: use WSL |
| A sandboxed `rm -rf` or `mv` of a directory fails with `Device or resource busy` (Linux) or `Operation not permitted` (macOS) | The directory is or holds a protected path: the project's `.venom/`, `.claude/` or `.mcp.json`, or a credential directory such as `~/.ssh` when the workspace is your home | Do it yourself in a terminal, or work in a directory narrower than `$HOME` |
| `Project config changed since you trusted it`, or doctor shows trust as `suspended` | The project gained a hook, MCP server, allow rule or similar after you trusted it | Review it with `venom trust` and confirm (`venom trust --yes` without a terminal) |
| A project's hooks, MCP servers or allow rules do nothing | You haven't trusted the project, or chose "Decide later" | Run `venom trust`, or start once with `--approve` |

## Still stuck {#more}

- `venom doctor --json` gives the full report to paste into an issue (it contains no keys).
- `venom --help` lists every command; `venom <command> --help` shows a command's flags.
- The [CLI](/docs/cli.md) and [Configuration](/docs/configuration.md) sections have the full reference.

## Related

- [Install venom](/docs/getting-started/install.md)
- [Local or cloud models](/docs/getting-started/local-or-cloud.md)
- [Your first gear](/docs/getting-started/first-gear.md)
