# 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 `/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](https://buildwithnexus.dev/docs/models#rejected-key).

## 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_PROXY` to the proxy (`http://`, with `user:password@` if it needs one). The launcher uses it. 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](https://buildwithnexus.dev/docs/install#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](https://buildwithnexus.dev/docs/install#cargo-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](https://buildwithnexus.dev/docs/install#managed-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`. For Ollama, setup 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](https://buildwithnexus.dev/docs/models#local-models).

## 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](https://buildwithnexus.dev/docs/multimodal).

## 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. Shell commands are confined separately, and that confinement is on by default. See [Permissions & hooks](https://buildwithnexus.dev/docs/hooks#sandbox).

## A saved session will not open

A session file is JSON Lines. bwn lists, exports and resumes it, including an older file that is one JSON object, and converts that file the next time it saves it. Reading a file does not change it. Upgrade with `npm install -g buildwithnexus@latest` if the installed bwn cannot read the file. The layout is under [Session files](https://buildwithnexus.dev/docs/data#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, bwn exits at once with status 129.

## Uninstall

See [Uninstall](https://buildwithnexus.dev/docs/install#uninstall) on the Install page.

[Next: Changelog →](https://buildwithnexus.dev/docs/changelog)

MIT licensed · Made by [Garrett Eaglin](https://garretteaglin.com/)
