Troubleshooting

Documented against OpenRig 0.7.7. Help text uses "node" where these pages say seat, for a seat's position in the running rig.

Start with the installation, not the rig

rig preflight asks whether this machine can run OpenRig at all. rig doctor checks the install, provider sign-in, writable paths, the daemon port and, where it applies, cmux control; --spec compares a spec against the running rig of the same name. Both work without a running daemon.

rig preflight
rig doctor
rig doctor --spec ./rig.yaml

The daemon

rig daemon status says whether it is up; logs --follow reads what it tried and refused, in its own voice. stop has a shutdown budget and exits non-zero on an incomplete drain, so a non-zero stop is a fact to inspect, not a failure to retry blindly. After a reboot, rig start brings the daemon, the kernel rig and the rigs that were last running back in one move; --last, --all and --rigs are the headless forms. When the daemon is down, rig crash-cart emits the recovery verdict and discovery as JSON without changing anything, and bare rig opens the same recovery cockpit interactively.

rig daemon status
rig daemon logs --follow
rig start --last
rig crash-cart

On a large database, startup can outlast its readiness deadline. rig daemon start then says startup is still pending and exits nonzero, but leaves the daemon running; a second start stays blocked, and rig daemon stop can't reach that process yet. Follow the message: it names the process, its address and the log, and gives the manual restart. Don't start again over it.

The running daemon records its process, port and database path in daemon.json in the OpenRig home folder, and the CLI reads it to find the daemon. A message that daemon.json is missing or malformed means the CLI can't tell which daemon is running; read rig daemon status and the log before starting another.

Two optional settings guard against reaching the wrong daemon. daemon.db_conflict set to stop keeps a second daemon off a database another live daemon holds (the default, warn, only warns); rig daemon start --allow-db-conflict proceeds for one start. On a Mac, transport.local_user_guard makes the CLI refuse a local daemon that runs as another user. It is a guard, not authentication. See Configuration.

A seat looks stuck

Read the record before the pane. rig parked diagnoses stopped seats that owe work; a held row is healthy only while its recorded wake is live. rig heartbeat shows whether in-flight work is being proven, and --nudge sends informational reminders without touching the rows. rig health lists read-only, explainable findings for a seat, a rig or the instance, with severity and status, and rig health explain <finding-id> shows the window, source, rule, evidence and confidence behind one. Empty output is never a healthy assertion. Then, and only then, tmux attach or rig capture the pane, and rig launch <rig> <seat> to start one stopped seat without disturbing the rest. A running seat is left as it is; for a fresh occupant there, use rig seat launch <seat> --fresh --stop --reason "<why>".

rig parked --rig my-rig
rig heartbeat --rig my-rig
rig health --rig my-rig
rig health explain <finding-id>
rig launch my-rig dev.impl

A fresh seat stopped at a native prompt (Claude's bypass-permissions warning, a login or a folder-trust question) keeps its startup context. rig up, rig bundle install and rig ps --nodes print "Startup attention" or "Startup details" for it, ending with the command to run. Once the prompt is answered in that seat's terminal, rig seat continue <seat> delivers the context in the same conversation without relaunching; if it reports an unknown outcome, check rig seat status <seat> before trying again.

rig seat continue <seat>
rig seat status <seat>

Help uses "node" where this page says seat, for a seat's position in the running rig.

Restore came back mixed

A restore is not all-or-nothing. Outcomes are reported per seat: resumed or rebuilt, started fresh or fresh-primed, waiting on a decision or attention, or failed. Mixed outcomes are normal output. Use rig ps --nodes for the live state of the current rig (-A for all rigs), then decide whether to keep a fresh seat, relaunch one, or restore again from a specific snapshot with rig restore-check first.

Service-backed rigs

For a rig that manages an application, rig env status <rig> is the honest health surface; rig env logs and rig env down follow. Do not infer environment truth from rig ps alone.

Last resort

rig destroy is the guarded destructive surface for bad local state: --state recreates an empty state root, --all also removes managed tmux sessions, --backup moves state aside instead of deleting it, and both --yes and --confirm destroy-openrig-state are required. It is the end of the list, not the start.

The web UI

rig ui open still exists as a verb. The web UI is in maintenance mode with best-effort support, and since 0.6.4 the daemon does not serve it unless you run rig config set ui.enabled true and then stop and start the daemon; while it is off, rig ui open prints those steps. The CLI and the terminal UI are the supported surfaces; never diagnose product behaviour from the web UI.

The troubleshooting family

Getting help

rig context get help prints the installed guide for helping a user get unstuck (it needs a running daemon). The same text is at /help/agents.

Where it goes next

• Continuity: snapshots, restore-check and handover.
• The terminal UI: the HEALTH tab shows the same findings rig health lists.