buildwithnexusv0.20.0
Menu

Troubleshooting

Start with bwn doctor. It checks your provider with a live request, lists the tools it found, and reports whether a sandbox backend is available.

bwn doctor

My API key was rejected (HTTP 401 or 403)

The key is wrong, revoked, or belongs to another account or project. Environment variables such as ANTHROPIC_API_KEY override the key bwn stored, so check whether one is set in your shell before you replace the stored key.

More in Models & providers.

The first-run download failed

The launcher downloads the binary for your platform from the GitHub release and verifies its checksum. Without a terminal, as in CI, it downloads only when you pass --bootstrap or set BWN_ALLOW_BOOTSTRAP=1.

More in Package security.

The binary will not start

The launcher runs the new binary once before it says it is ready, and says why when it cannot run. The usual causes are:

Ollama does not respond, or the model is missing

Start the server with ollama serve and pull a coding model, for example ollama pull qwen2.5-coder. Setup for Ollama only checks that the model is installed, so a model that is not pulled shows up as an error that names its ollama pull command. More in Models & providers.

Pasted images do not draw

Real-pixel previews need kitty 0.28 or later, Ghostty, WezTerm with placeholder support, or a Sixel terminal. Sixel and half-block previews need ffmpeg on your PATH. Other truecolor terminals get half-block art, and line mode (--plain) always does. See Multimodal input.

bwn asks too often, or not enough

Change the mode with /permissions, for example /permissions accept-edits, or start with --permission-mode. ask is the default, accept-edits applies file edits inside the project without a prompt, auto runs commands and edits without asking, and readonly refuses every change. Allow, ask and deny rules in settings.json tune individual commands. The gates prevent mistakes and are not a sandbox. See Permissions & hooks.

A saved session will not open

A session saved or resumed by 0.20 is a new file format. 0.19 and earlier list it as corrupt and skip it, and they do not change the file. 0.20 opens sessions from every earlier version. Upgrade with npm install -g buildwithnexus@latest if an older bwn is the one that cannot read the file. The layout is under Session files.

The terminal closed and bwn kept running, or it exited 129

When the terminal disappears without a hangup signal, such as a dropped SSH session or a closed tab under some multiplexers, 0.20 exits at once with status 129. Versions before 0.20 read end-of-input in a loop instead, which pinned a CPU core and never exited. If a bwn process is still doing that, upgrade.

Uninstall

See Uninstall on the Install page.

Next: Changelog →