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. The sections below cover what it usually points to, with a link to the full explanation.

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 /login in 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 NODE_USE_ENV_PROXY=1 next to HTTPS_PROXY (Node 22.21+ or 24.5+). A TLS-inspecting proxy also needs its CA in NODE_EXTRA_CA_CERTS.
• Download blocked entirely: build or download the binary yourself and set BWN_BIN to its absolute path.
• Home directory mounted noexec: set NEXUS_HOME to 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 --locked or 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.

Uninstall

See Uninstall on the Install page.

Next: Changelog →