Troubleshooting

This page covers symptoms and fixes for installation, the daemon, login, models, search, session recovery, and protocol connections.

On this page

• Fix installation problems
• Check the daemon
• Check login and models
• Check search and the browser
• Recover sessions and context
• Check connections

Fix installation problems

snowpea: command not found

Symptom: The shell prints snowpea: command not found right after installation.

Cause: ~/.local/bin is not on the PATH of the currently open shell. The installer appends the line to your shell profile, but it cannot change an already-open shell.

Fix:

1. Open a new terminal, or source the shell profile.
2. Check the install location and current PATH.

ls ~/.local/bin/snowpea
echo $PATH

3. Check whether you changed the install location with SNOWPEA_BIN_DIR.

The installer failed partway through

Symptom: The installer stops before completing.

Cause: A network, permission, or tool installation step failed. The installer script is idempotent.

Fix:

1. Run the installer again.
2. If it stops at the same step, run the dry run to see what it is trying to do.

curl -fsSL https://raw.githubusercontent.com/Wafour-Developer/snowpea-agent/main/installer/install.sh -o install.sh
sh install.sh --dry-run

3. Run the failing step by hand.

curl -LsSf https://astral.sh/uv/install.sh | sh     # uv
uv tool install snowpea-agent

Behind a corporate proxy, or offline

Symptom: uv tool install fails behind a corporate proxy or on an offline machine.

Cause: uv tool install needs access to PyPI.

Fix:

1. Set HTTPS_PROXY before running the installer.
2. For offline installation, bring in a wheel and install it directly.

uv tool install ./snowpea_agent-0.1.0-py3-none-any.whl

3. Set SNOWPEA_WHEEL_URL and SNOWPEA_INSTALL_SOURCE to override where the installer gets the package.

The terminal UI will not start — Node is missing or too old

Symptom: The terminal UI (TUI) does not start.

Cause: The TUI needs Node 20 or later. Headless runs and every snowpea subcommand work without Node.

Fix:

1. Install Node 20 or later from your package manager or nodejs.org.
2. Check the Node version.

node --version

3. Run snowpea again.
4. To verify behavior without the TUI, use a headless run.

snowpea -c "hello" --json

After an update: Cannot read properties of undefined (reading 'rawCall')

Symptom: After an update, Snowpea prints Cannot read properties of undefined (reading 'rawCall').

Cause: State left by an older automatic update does not match the current runtime code.

Fix:

1. Force a reinstall of current main.

uv tool install --force --reinstall 'snowpea-agent[images] @ git+https://github.com/Wafour-Developer/snowpea-agent@main'

2. When no work is running, stop the daemon.

snowpea daemon stop

3. Launch snowpea again so the new daemon code is loaded.

Check the daemon

The daemon will not start

Symptom: The daemon (snowpea core) does not start.

Cause: The daemon log may contain the startup failure, or a stale process may still hold the recorded port.

Fix:

1. Check $SNOWPEA_HOME/logs/daemon.log.
2. Check daemon status and restart it.

snowpea daemon status
snowpea daemon stop
snowpea daemon start

3. Delete daemon.json if the pid recorded in it is already dead.

The port is already in use

Symptom: The daemon reports that the port is already in use.

Cause: At start-up, the daemon chooses a loopback port and records it in $SNOWPEA_HOME/daemon.json as {port, pid, token, startedAt, protocolVersion}. Almost every port conflict means an older daemon is still alive, or a dead daemon left daemon.json behind.

Fix:

1. Check whether the recorded pid is alive.

snowpea daemon status      # is the pid alive?

2. Stop the daemon.

snowpea daemon stop

3. If another program is using that port, restart the daemon so it chooses another port.
4. To probe the daemon actively, call /health.

curl "http://127.0.0.1:$(python -c 'import json;print(json.load(open("'"$HOME"'/.snowpea/daemon.json"))["port"])')/health"

exit 3 — could not connect to the daemon

Symptom: A headless run exits with exit 3.

Cause: No daemon is running, or the client cannot reach it. A different SNOWPEA_HOME uses a different daemon.

Fix:

1. Check daemon status.

snowpea daemon status

2. Check whether you are passing an unusual SNOWPEA_HOME.

Different projects can see each other's sessions

Symptom: Different projects show the same session list.

Cause: One SNOWPEA_HOME uses one daemon and one set of sessions.

Fix:

1. Split SNOWPEA_HOME when projects need isolation.

SNOWPEA_HOME=~/.snowpea-work snowpea
SNOWPEA_HOME=/tmp/snowpea-ci snowpea -c "…" --mode plan

2. For headless runs, use --home DIR.

Check login and models

Device-code login fails with HTTP 403

Symptom: Device-code login prints device authorization failed (HTTP 403).

Cause: Some networks or accounts can return HTTP 403 even when the same request works elsewhere. The wizard prints the vendor's own error text and asks for the authentication method again.

Fix:

1. In the wizard, choose 1=API key and paste a key.
2. Or choose 3=OAuth token and paste a token.
3. From the command line, set an API key.

snowpea setup --vendor openai --key sk-your-key-here

4. When entering a token from the command line, omit the value so it stays out of shell history.

snowpea provider login openai --token      # omit the value so it stays out of shell history

login_unsupported

Symptom: Login prints login_unsupported.

Cause: Only openai (device code) and openrouter (OAuth PKCE) support browser login. Gemini uses Google ADC login, and every other vendor returns login_unsupported with the command to run instead.

Fix:

1. Run the setup command required for that vendor.

snowpea setup --vendor deepseek --key sk-your-key-here

It says the provider is not configured

Symptom: Snowpea says the provider is not configured.

Cause: The selected vendor is determined by the SNOWPEA_PROVIDER environment variable, then --provider on the command line or the session's provider argument, then providers.default in settings.json, then the first configured vendor. If requests go to an unexpected vendor, SNOWPEA_PROVIDER may be exported somewhere.

Fix:

1. Inspect the configured provider list.

snowpea provider list
snowpea provider list --json

2. Check whether SNOWPEA_PROVIDER is set.

Logging into Gemini on a remote or headless machine

Symptom: A remote or headless machine has no browser for Gemini login.

Cause: On a desktop, snowpea provider login gemini opens Google's ADC login.

Fix:

1. Log in with token input.

snowpea provider login gemini --token

2. Omit the value to enter it at a hidden prompt and keep it out of shell history.

The local model talks but never does anything

Symptom: The local model can chat but does not execute tool calls.

Cause: Any server that speaks /v1/chat/completions can connect, but tool calling must be supported by the loaded model. If the model does not support tool calls, the agent can converse and cannot act.

Fix:

1. Load a model that supports tool calling.

snowpea setup --vendor local --base-url http://localhost:11434/v1 --model qwen3:8b

Check search and the browser

The browser tool wants to download a binary

Symptom: The browser tool says it will download a binary.

Cause: The default browser provider local_chromium drives headless Chromium through Playwright. If the binary is not present, the first run downloads it.

Fix:

1. On an online machine, allow the download.
2. On an offline machine, fetch the binary in advance or turn the browser category off.

snowpea setup --tools -browser

3. Other providers (camoufox, browser_use_local, browserbase, firecrawl_cloud) answer browser_provider_unavailable until they are configured.

Web search does not work

Symptom: Web search does not answer.

Cause: The configured search provider may be unavailable, or a provider that requires a key has no key. ddgs is the only provider that needs nothing.

Fix:

1. Run a real query to see the provider that answered and the reason each skipped provider dropped out.

snowpea search test "snowpea agent github"
snowpea search test "snowpea agent github" --json
snowpea tools list --json

2. If tools list shows web_search as exa_free → ddgs, the configured id could not run and something else took over.
3. If you selected a key-required provider, configure the key.

web_extract refuses a URL

Symptom: web_extract refuses a URL.

Cause: Private, loopback, and link-local addresses are refused. Fetched pages are truncated at tools.max_output_chars (20000 by default).

Fix:

1. Use a publicly reachable URL.
2. If output is truncated, adjust tools.max_output_chars.

A media tool answers tool_inactive

Symptom: A media tool answers tool_inactive.

Cause: image_generate, video_generate, music_generate, and text_to_speech are always registered but stay inactive until credentials exist.

Fix:

1. Configure credentials for the media provider.
2. After configuration, the tool state changes to active without a restart.

Recover sessions and context

The context window is full

Symptom: Past 85%, the status line goes red and a row appears: [!!] context 85% — /compact to free space.

Cause: The current conversation is near the model context window limit. ctx 12.3k used with no percentage means the daemon does not know this model's window size.

Fix:

1. Run /compact and include optional instructions for what to keep.

/compact keep what we changed in this refactor

2. The daemon also compacts on its own before a turn would pass context.autoCompactPercent.
3. If no percentage appears, set providers.<vendor>.context_window.

/resume is refused

Symptom: /resume or /sessions is refused.

Cause: Swapping the transcript under a live turn would make the current turn's transcript inconsistent. For the same reason, a live session is not deleted and /session clear skips it.

Fix:

1. Wait for the current turn to finish.
2. Or press Esc to interrupt the running turn, then try again.

Check connections

protocol_incompatible

Symptom: protocol_incompatible is printed.

Cause: The client and the daemon disagree on the protocol major version. This can happen when the package was upgraded while an older daemon is still in memory.

Fix:

1. Stop the daemon.

snowpea daemon stop

2. Check the version.

snowpea --version

3. Run snowpea again.

snowpea

4. In the desktop app, check the bottom status bar for the protocol version both sides agreed on, and upgrade the app and core together.
5. The current protocol is 1.5.0; the full schema is in the protocol reference.

unauthorized

Symptom: unauthorized is printed.

Cause: Either a method was called before system.hello, or the token is wrong. The token is in $SNOWPEA_HOME/token, and the first call after connecting must be system.hello.

Fix:

1. Check that the first call in your client is system.hello.
2. Check that the token comes from $SNOWPEA_HOME/token.
3. Read the handshake section of Protocol.

Ask for help

Include the logs, version, status, and command needed to reproduce the issue.

1. Prepare the last 50 lines of $SNOWPEA_HOME/logs/daemon.log.
2. Prepare the output of snowpea --version and snowpea daemon status.
3. Prepare the one command that reproduces it.
4. Open an issue.

Next steps

Read the FAQReview common concepts and choices.→Review installationCheck requirements and install steps.→