Troubleshooting

Start with:

mimir doctor --json

Doctor is read-only. It reports the failed check and a repair command or activation step. Apply that repair, then run doctor again.

Common repairs

Failure	Repair
Invalid local connection	mimir login
Stale Worker API or bundle	mimir deploy
Missing or outdated managed file	mimir install
Modified or conflicting managed file	Review the preserved file, then restore or remove it before running mimir install
OpenCode integration is staged	Restart OpenCode
Hermes integration is staged	Restart Hermes
Claude Code integration is staged	Run /reload-plugins or restart Claude Code
Codex integration is staged	Restart Codex
Cursor integration is staged	Open or continue an agent session
Hermes plugin is disabled	hermes plugins enable mimir
Hermes OpenRouter route is stale	mimir update
Hermes OpenRouter credential is missing	Configure OpenRouter authentication in Hermes

Setup and login errors

cloudflare_auth_required

Rerun the command without --json and complete Wrangler’s browser approval.

openrouter_key_required

Set OPENROUTER_API_KEY in the environment or rerun mimir setup and enter it at the masked prompt. Do not pass the key as a command argument.

mimir_token_required

Set MIMIR_TOKEN in the environment or rerun interactively.

deployment_missing

Run mimir setup. If Mimir is deployed in another Cloudflare account, authenticate Wrangler to that account and run mimir login again.

deployment_url_missing

Run mimir deploy, then mimir login. If Wrangler cannot recover the URL, find it in Cloudflare and run mimir login --url <url>.

Installation reports action_required

Mimir found a modified, conflicting, or unsafe path and left it unchanged. Review the reported file. Restore the Mimir-owned version or remove the file if it is disposable, then run mimir install again.

Dashboard Access fails

The Access application must protect these paths:

• /dashboard/auth
• /dashboard/api/*
• /dashboard/log-objects/*

Do not protect the bare host or /login. See Dashboard Access.

Harness capture is missing

Run doctor, apply its repair, and restart or reload the harness. See the capture setup page for OpenCode, Hermes, Pi and Oh My Pi, or other harnesses.

Session state looks wrong

disconnected means no event has arrived for about 90 seconds. About ten minutes of silence finalizes the session. New activity with the same session ID can reopen it.

For pending, partial, or failed capture, follow Verify capture. Inspect Worker logs and the R2/D1 bindings only if failures remain after background writes settle.