Troubleshooting

Start with the symptom you see. Each section says what to check and how to fix it.

The runner is offline

minga status

• “not running”: start it with minga runner start. If you installed the service, that starts the service; if not, it starts the runner in the background.
• “reconnecting”: the runner cannot reach Minga right now. Check the network; it retries by itself.
• “unauthorized”: Minga no longer accepts this runner’s token, for example because the runner was revoked in the app. Pair it again: minga runner logout, then minga runner login.
• “not paired”: run minga runner login.

Logs:

What	Where
The runner’s log	~/.local/state/minga/runner.log
The service’s output (macOS)	~/.local/state/minga/runner.stdout.log and runner.stderr.log
The service (Linux)	journalctl --user -u minga-runner.service

If the service does not come up after a reboot on Linux while you are logged out, enable lingering: sudo loginctl enable-linger $USER.

If you installed a CLI in a new place after installing the service, the service may not find it: run minga runner install again so it picks up your current PATH.

Work says “waiting for a runner”

The item is ready, but no runner that can take it is online. Check:

• Is a runner online? Settings › Runners shows each runner’s state. A sleeping laptop counts as offline.
• Does it have the right CLI? If the worker’s preset prefers Codex, a runner with only Claude Code won’t take it.
• Does the profile serve this workspace? minga profile list shows each profile’s workspaces. Widen it with minga profile scope <id> --all.
• Is the profile signed in? minga profile check.
• Does the runner have the repo? Project settings › Repositories shows, per runner, whether it has a clone. If not, open the repo once in Claude Code or Codex on that machine, or run minga repo add <path> there.
• Is it at capacity? A runner takes four runs at a time by default.

The run starts on its own as soon as a runner can take it.

minga profile check reports a problem

Problem	Fix
Signed out	Sign in to that CLI home again, with the CLI’s own login or key setup. For a second home, set CODEX_HOME or CLAUDE_CONFIG_DIR to it first.
The CLI is not found	Install it, or point the profile at it with minga profile add … --cli-path <path>. Then minga runner install so the service sees it.
The home does not exist	Check the --home path in minga profile list, or add the profile again.
Rate limited	The provider’s limit for that login is reached. Runs on that profile wait; another profile can take them.

The MCP connection fails

• Sign in again: claude mcp login minga, or codex mcp login minga.
• Disconnect and reconnect: Account (your avatar) › Connected apps › Disconnect, then sign in again from the terminal.
• Codex picked the wrong registration method: Minga registers clients dynamically (DCR). If Codex fails while registering, run codex mcp login minga --oauth-client-registration dcr.
• “No project ‘x’ for you”: list_projects shows the projects you can reach; pass the slug or the repo’s remote.
• “Too many Minga calls”: the limit is 120 calls a minute per person (10 for ask_lead). Wait a minute.
• “Request too large”: a call may carry at most 1 MB. Split a large plan into several calls.

Lea can’t work

Her chip says why. See Choose where Lea runs.

• away: her runner is offline. Start it, or let her think somewhere else.
• can’t work: no usable model key for cloud thinking (Settings › Model providers), or the person who looks after her left (take her over in Project settings › Lea).
• paused: Resume in Project settings › Lea. Messages sent meanwhile wait for her.

A run ended in a way you did not expect

Every run ends with a stated reason. Open the run from the item or the runs list to see it and the transcript.

Reason	Usually means	What to do
the runner went offline	The machine slept or lost its connection	Keep a machine online for long work. The item is tried again once; after a second loss you get a card.
Minga’s tools didn’t load in the CLI	The run could not reach Minga’s MCP server	Check the runner’s network and minga update; then retry the item
auth error	The CLI is signed out, or a key was refused	minga profile check; sign in again
permission denied	A needed permission was denied (by you, or by Codex’s reviewer three times)	Allow it next time, change the access mode, or do that step yourself
rate limited	The profile reached its provider’s limit	Wait, or add another profile
sandbox error	The worktree or environment could not be prepared	Check minga repo list and free disk space
max turns, wall clock, context exhausted	The run hit a limit	Split the item, or tighten its spec

Note

An item that keeps failing stops on its own: after 5 attempts that changed nothing, or 20 attempts of any kind since a person last acted, it waits for you in Needs you.