troubleshooting

bise doctor checks your Mac, the install, your keys and models in one command. start there.

#bise doctor

bise doctor

it checks this Mac, the install, your keys, each role's model and the running bise, without the network and without printing a key. each line is ✓ (fine) or ? (worth a look), and every ? says how to fix it:

checking your setup

✓ macOS       macOS 15.5 arm64
✓ bise        bise 3f2a91c0 (darwin-arm64) · ~/.local/share/bise/versions/3f2a91c0/bise
✓ home        ~/.bise (default): config.toml ✓, auth.json ✓, hubs/ ✓, sessions/ ✓
✓ git         git version 2.50.1
✓ github      gh logged in; this repo's PRs: github.com/you/your-repo
✓ keys        anthropic (auth.json), mistral (env MISTRAL_API_KEY)
✓ main        anthropic/claude-opus-5-5 · high
✓ agents      same as main
✓ small jobs  anthropic/claude-haiku-4-5 · titles, summaries
✓ voice       mistral/voxtral-transcribe-3 · language auto · listens when you talk
? PATH        `bise` is not on PATH
              fix: add ~/.local/bin to PATH (the installer does it; open a new terminal)

? 1 thing to check. it says how.

bise doctor --verbose says more on each line.

#common problems

#bise: command not found

~/.local/bin isn't on your PATH yet. open a new terminal, or run ~/.local/bin/bise. the installer adds the line to your shell's rc file unless you passed --no-modify-path.

#a key doesn't work

bise providers               # where each key comes from
bise auth check anthropic    # one tiny call; says what failed

a key saved in bise (~/.bise/auth.json) wins over the one in your environment. if you changed the key in your shell, bise logout <provider> drops the saved one. when the check says the account has no credit, it links the provider's billing page.

#unknown provider 'x'

the part before the first / of a model name must be a provider bise knows, or one you added under [providers.x] in config.toml. bise models lists them. see gateways and local models.

#no answer from a local model or a gateway

no answer from localhost:11434 in 90 s (timeout) means the server sent nothing for 90 s. a local model reading a long prompt can take longer: raise idle_timeout_sec for that provider. see a slow server.

#a key doesn't reach bise in Ghostty

cmd+v with an image, cmd+f, cmd+k, cmd+a and cmd+↑↓ need one line each in Ghostty's config: bise setup ghostty, or /setup.

#a remote MCP server has no tools

bise plugins (or /plugins) shows each server's state. needs a login: run bise plugins login <server>. a header that uses an unset variable leaves the server out and names the variable.

#an agent seems stuck

look for ? in the panel: it may wait for you in the inbox (ctrl+1). /interrupt in its view stops its turn, and a message starts the next one. /stop <agent> also takes its hands off Chrome and your apps.

#logs

bise session show            # the newest session's transcript
bise session show <id>       # one session (a prefix of its id works)
bise session show --context  # what the model sees now

#still stuck

open an issue on GitHub with the output of bise doctor and what you did. it never prints a key, so you can paste it as it is; check it holds no private path you'd rather keep.