Troubleshooting
Common issues and how to resolve them.
Daemon won't start
Check if port 7433 is already in use by another process. You can verify with lsof -i :7433 on macOS/Linux.
Run rig daemon status to check the current state of the daemon. If it reports a stale PID file, remove it with rig daemon clean and try again.
Agent shows READY but isn't responding
The agent process may have stalled or hit a prompt that is blocking execution. Attach to its tmux session directly to inspect:
tmux attach -t <session-name>
If the agent is stuck at a prompt, you can respond manually or restart it with rig restart <node-name>.
Restore failed
Check rig ps --nodes for any nodes showing WARNING status. A failed restore usually means the agent launched with a fresh context instead of restoring from its last snapshot.
The agent is still running — it just does not have its previous context. You can manually feed it the last snapshot with rig restore <node-name> --force, or let it continue fresh and rebuild context naturally.
More troubleshooting guides coming soon.