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

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.

Edit or write refused after a change-contract reservation

Match the tool text, then stop. A retry of write, edit, or multiedit does not retire the reservation. Disabling auto-checkpoint does not either. Mutation aftercare is the contract commit; auto-checkpoint is a separate git commit.

Tool text	What is true	What to do
change contract mutation admission: effect observation requires reconciliation	The live memory or file owner still holds an effect-observation ticket.	Inspect. Do not waive obligations and do not switch store mode.
change contract mutation admission: change contract mutation requires reconciliation	The older observation-ID reservation is still pending.	Same inspection. That ID is not a source-bound ticket.
persist mutation aftercare or persist failed direct mutation evidence	The effect may already be on disk. Owner persistence did not finish, and it is not retried.	Read the diff. Keep the same data directory if file mode is on.
change contract snapshot write failed:	Storage is faulted. The suffix is the owner error, often change contract persistence failed.	Reopen that same owner. Do not delete the snapshot to clear the fault.
pending staged effect; use recovery_only=true for aftercare	Staged acceptance already observed the batch.	Call staged_accept or staged_accept_all with recovery_only true.
effect observation capacity exhausted	The owner refused before the effect. Nothing was evicted to make room.	Wait until an older ticket in that session settles. Do not delete obligations.

Inspection that is still allowed:

1. Ask for contract_list_obligations on the current session. A success body is JSON with session_id, generation_id, and obligations. Pending aftercare does not add a ticket field. A successful list while the edit stays refused means the ticket is still pending.
2. Ask for contract_preflight_report when you want the dry path report. It does not run commands and does not settle the ticket.
3. For a proposal, run bmo workstream proposals get <proposal-id>. Aftercare failure leaves status: conflicted even if the files changed. Then run bmo workstream proposals diff <proposal-id>.

contract_waive_obligation returns the same admission error while the ticket is pending. A waiver is not aftercare.

Staged recovery with recovery_only true commits the observed ticket only. It does not write files. A clean result has "status": "reconciled". invalid or stale effect observation means this call does not match the observed batch. After a process restart, only staged_accept_all with recovery_only true and an empty staging area can settle exactly one observed staged_accept ticket still held by the owner. A missing or second match is rejected. That restart path does not restore staged file contents.

File-owner startup text, the per-source recovery matrix, and the commands that must not be used to hide a snapshot are in the repository runbook Operating the change-contract file owner.

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.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.

Remove BMO

To uninstall the current user’s BMO install, quit open sessions and follow Uninstall. The dry run prints every path before anything is deleted.

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