Troubleshooting

First run: no model or provider configured

Start with the symptom you can observe: provider status, authentication, a stuck session, or a failing tool. The checks below are ordered so you can verify the runtime state first, then change keys, models, or local environment only when the evidence points there.

If BMO starts but every turn fails with a provider or model error, no usable provider is configured for the selected model.

List what BMO sees: bmo config show-provider-status (or /provider-status in the TUI, or GET /v1/provider-status) reports which providers are configured, ready, or ambiguous.
Export a provider key in the same shell that launches BMO (see Authentication).
Switch to a model that matches a ready provider with /model.

Authentication errors

”Invalid API key”

Check that your environment variable is set: echo $ANTHROPIC_API_KEY
Verify the key hasn’t been rotated in your provider dashboard
Make sure you’re exporting the right variable for your provider (see Authentication)

“You have exceeded your rate limit”

Slow down or switch to a model tier with a higher rate limit. Some providers offer higher limits with usage plans.

If rate-limit errors are recurring, BMO automatically attempts a bounded recovery cascade (cap retry → same-provider model swap → cross-provider chain → opt-in local last-resort). See the TPM recovery feature page for inspection commands (bmo config show-tpm-recovery --runtime, /recovery TUI slash, GET /v1/tpm-recovery/posture).

Session issues

BMO gets stuck and never responds

Check your internet connection
Press esc to interrupt the current turn. ctrl+c opens the quit confirmation dialog.
Check provider status pages for outages
Try a shorter prompt or a different model

Context window exceeded

BMO should handle this automatically via Context Pruning. If you’re seeing errors:

Check /context for the latest prompt-budget preflight snapshot and recovery outcome
Leave options.pruning.* and options.enable_auto_summarize enabled unless you are intentionally debugging context shape
Disable prompt-expanding features such as options.pruning.type_inject_for_read if you opted into them
Start a fresh session with /new in the TUI

Tool failures

”Permission denied” on file write

Check file permissions: ls -la <file>
If using the Execution Sandbox, verify the sandbox allows writes to the path

”Command not found” in bash tool

The agent’s shell environment may differ from your interactive shell. Make sure required tools are in $PATH before launching BMO, or start BMO from the same environment where those tools already resolve.

LSP not responding

Ask BMO to use the lsp_restart tool, or restart BMO
Check that the LSP binary is installed and in $PATH
Verify your [lsp.<name>] config points to the correct binary, or rely on auto-LSP root detection if you have not configured an explicit server

MCP issues

MCP server not connecting

Confirm the server is running: check logs or process list
Verify the url in your MCP config matches the server address
For SSE transport, check firewall rules

MCP tools not appearing

After changing MCP config, restart BMO so it can reconnect and rebuild the tool list for the session.

Build and install issues

”go: command not found”

Install Go from go.dev/dl. BMO requires Go 1.26.6 or later.

Build fails with module errors

cd bmo && go mod tidy && go build ./...

Resource usage

Embedding sidecar memory or startup

The local embedding sidecar (bmo-embedding) runs as a separate process and uses roughly 500–700 MB of RAM while active. It starts lazily on first embedding use, so memory pressure or a slow first semantic-search call usually traces here.

On machines with under ~2 GB of free RAM, disable it with [options.embedding] enabled = false (see Installation — Embedding service memory).
Disabling it does not affect persistent-memory embeddings, which use a separate code path.

Getting more help

Search GitHub Issues
Check the FAQ
Open a new issue with your Go version, OS, BMO version (bmo --version), and steps to reproduce