Skip to content
Docs menu

Troubleshooting

Diagnose a venom setup with venom doctor and fix the common install, endpoint, key, model, sandbox and trust problems.

View .md

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 first

venom 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 --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 and Configuration sections have the full reference.