operations
🧯 Troubleshooting Matrix
Symptoms, likely causes, and first safe checks across wiki, OMP, Hermes, Moincraft, Nexus, and AIRI.
| Symptom | Likely cause | First safe check |
|---|---|---|
| Wiki page exists in content but not output | Hugo build not rerun or front matter invalid | npm run wiki:build from /home/mc/wiki |
| Generated Hermes page stale | wiki:content not run after Nexus JSON changed |
npm run wiki:content from /home/mc/wiki |
| Hugo binary missing | PATH missing local wrappers | Use package scripts or prepend /home/mc/bin:/tmp/dart-sass. |
| Sidebar order wrong | Missing or duplicate weight |
Check front matter on _index.md and pages. |
| Dashboard cannot connect | Relay/dashboard port down or auth mismatch | From /home/mc/moincraft, run the smallest relevant runtime check; inspect stack
. |
| Bot stuck in action loop | In-world command loop or pathfinding/action queue state | Send !stop; follow operator
. |
| Viewer blank | Bot not spawned, chunks not loaded, version/render mismatch | Lower view distance; see viewer . |
EADDRINUSE on viewer/relay |
Duplicate PM2/systemd/manual process | Use one orchestrator; see stack . |
| Discord launcher says no secret | OMP process loaded env before secret was added | Restart omp --allow-home; check /discord-launcher-status. |
Pi plugin starts pi instead of OMP |
Plugin default spawn command | Set spawn command to /home/mc/.local/bin/omp-plugin-env. |
| Nexus data looks stale | Collector/build pipeline not rerun | Run only the affected Nexus script when safe. |
| Secret-like text found in output | Variable documentation or real leak | If it is a value, remove source and rebuild; if only a variable name, keep with context. |
Escalation order#
- Check the relevant source page.
- Run the smallest non-mutating verification command.
- If runtime state must change, use the owning project runbook.
- Rebuild the wiki only from source.
Sources: root AGENTS.md, OMP docs, Moincraft stack/security/debugging docs, Nexus rules.