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.
- Run
buildwithnexus login(or/loginin a session) to replace the stored key. bwn checks the new key with the provider before it saves it. - If the provider's variable is set, unset it or update it. A stored key does not win against it.
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.
- Behind a proxy: set
HTTPS_PROXYto the proxy (http://, withuser:password@if it needs one); since 0.19 the launcher uses it on every Node. A TLS-inspecting proxy also needs its CA inNODE_EXTRA_CA_CERTS. - Download blocked entirely: build or download the binary yourself and set
BWN_BINto its absolute path. - Home directory mounted noexec: set
NEXUS_HOMEto an absolute path on a filesystem that can run programs.
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:
- glibc older than 2.34. The prebuilt Linux binaries need glibc 2.34 or later, for example Ubuntu 22.04+, Debian 12+ or RHEL 9+. Under WSL, the distro you run needs it too.
- A musl system such as Alpine. The prebuilt binaries do not run there. Install with
cargo install buildwithnexus --lockedor build from source instead, as Install describes. - Endpoint protection. CrowdStrike Falcon or Microsoft Defender may block or quarantine the Windows binary. The launcher prints its path and SHA-256 and does not download it again on its own. See Managed and corporate machines.
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.