Troubleshooting

When something looks wrong

Start with muon doctor (machine-readable JSON, safe to script against) or muon onboard (the human-guided version). Both are read-only diagnostics and never reject on a degraded environment — every source that can't be read degrades to an honest “unknown” with a reason instead of a crash.

muon doctor --json     # scriptable capability preflight
muon onboard           # guided, human-readable checklist

A vendor CLI isn't found, or reads as logged out

MUON checks two things separately per vendor — installed and authenticated — and both muon doctor and muon onboard name which one is missing rather than a generic “not ready.”

Vendor	Reinstall	Re-authenticate
Claude Code	`npm i -g @anthropic-ai/claude-code`	run `claude`, sign in
Codex	`npm i -g @openai/codex`	`codex login`
Cursor	`curl https://cursor.com/install -fsS \| bash`	`cursor-agent login`
OpenCode	`curl -fsSL https://opencode.ai/install \| bash`	`opencode auth login`

Codex with a custom provider

If ~/.codex/config.toml selects a custom model_provider (e.g. Azure), MUON requires the exact env_key that provider declares — a cached native login does not authenticate a different selected provider. Set the provider's key in your shell environment (never a repository file) and launch MUON from a shell that has it, or switch back to a built-in provider and run codex login.

Kiro has its own guided check: muon kiro doctor. The common Kiro problems (profileArn errors, only auto listed, 0 seats, a refused folder) and their fixes are on the Set up Kiro page.

Each lane holds the roles it is best at, by design: Cursor takes review-class roles with a no-writes guarantee, and OpenCode scouts. If a dispatch is refused for a role, that is the role model working, not a fault.

The code index looks stale

MUON's embedded code graph indexes your workspace in the background as you commit. Check whether it has fallen behind HEAD:

muon version

The JSON includes brainCommit (what the graph is indexed at), headCommit (your actual HEAD) and stale (whether they disagree).

In the desktop app, open the graph/code panel and use Re-index — it's disabled while an index is already running, since indexing is exclusive per repository.
The MCP server opportunistically refreshes freshness on certain reads (code_impact), so a short lag often clears on its own.
A stale index degrades gracefully rather than lying: the orchestrator treats a stale or unindexed file as review-blind and routes it to a human rather than certifying a diff it can't see.

The brain doesn't seem to be running

“The brain” is MUON's embedded local backend. The desktop app supervises its own; the CLI auto-spawns one on first use for every command except version, shutdown, custom-agents and most mcp subcommands, which are deliberately brain-independent.

muon doctor          # reports connectivity honestly, even if the brain is down
muon mcp status      # whether a brain is running, and its port/pid
muon shutdown        # stop the CLI-spawned brain + runner cleanly
muon chat            # any ordinary command re-spawns one if none is found

If the desktop app and a CLI-spawned brain both start, MUON detects and adopts the already-running one rather than starting a second — muon doctor tells you which profile you're actually talking to.

Corrupt release state

~/.muon/release/channel-state.json records the newest signed release this Mac accepted. That record blocks rollbacks.

If MUON reports that this file is corrupt, quit MUON.app, then move the file aside and run the updater:

mv ~/.muon/release/channel-state.json ~/.muon/release/channel-state.json.bad
muon update

The accepted-sequence history restarts. The version floor still applies: MUON will never accept a version older than the installed MUON.

Never delete this file to get past a “rollback refused” or “verification failed” message. Those are protections, not corruption.

Where logs live

Path	What
`…/MUON/logs/brain.log`	Embedded backend log
`…/MUON/logs/runner.log`	Sandboxed runner boot, lease, dispatch and recovery log
`~/Library/Application Support/MUON/`	Everything else MUON persists locally — settings, the embedded SQLite brain, the graph store, the lockfile

How to reset

01
Stop everything cleanly first
Quit the desktop app, then run muon shutdown to stop any CLI-spawned brain and runner. Confirm nothing is left with muon doctor.
02
Wipe local state
Delete ~/Library/Application Support/MUON/. This removes the embedded brain, the graph store, the lockfile and settings — including unconfirmed memory proposals. Export first with muon memory pack export --out <dir> if you want confirmed decisions back afterwards.
Removing the data directory by hand is the current reset path — there is no muon reset command in v1.
03
Relaunch
Reopen the app or run any muon command; MUON reinitializes a fresh brain and re-indexes the workspace the next time it needs to.

Still stuck?

Send a mail with your muon doctor --json output attached — it never includes a credential value, only readiness booleans and reasons — to [email protected].

Previous← Governance