Troubleshooting
Diagnose a venom setup with venom doctor and fix the common install, endpoint, key, model, sandbox and trust problems.
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.
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 firstvenom 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
Install and start
| 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) |
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
| 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) |
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
| 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) |
| 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
| 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
| 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); 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
venom doctor --jsongives the full report to paste into an issue (it contains no keys).venom --helplists every command;venom <command> --helpshows a command's flags.- The CLI and Configuration sections have the full reference.