Troubleshooting

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

1. Check your internet connection
2. Press esc to interrupt the current turn. ctrl+c opens the quit confirmation dialog.
3. Check provider status pages for outages
4. 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

1. Ask BMO to use the lsp_restart tool, or restart BMO
2. Check that the LSP binary is installed and in $PATH
3. 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+.

Build fails with module errors

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

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