operations

🐞 Debugging

Server, bot, dashboard, PM2, and Linux debugging baselines for the Moincraft stack.

Debug closest to the failing layer.

Server debugging#

  • Paper crash reports live under server/crash-reports/.
  • For lag or hot-path questions, profile with Spark before tuning random knobs.
  • Structured server logging belongs in log4j2.xml; rotate files instead of letting logs grow without bounds.

Bot/runtime debugging#

  • Use node --inspect for live JS inspection and breakpoints.
  • Capture V8 heap snapshots when investigating leaks.
  • Rotate PM2 logs and avoid unbounded log retention.

Dashboard debugging#

  • Watch browser WebSocket frames for relay connectivity issues.
  • Turn on verbose Socket.IO logging when relay traffic is the suspected fault.
  • Treat “Connecting… forever” as a probable client/relay bug first, not a styling issue.

System debugging#

  • Use journalctl for service-level incidents.
  • Use disk-space triage for runaway log files.
  • EADDRINUSE usually means two orchestrators are fighting.

Common symptom table#

Symptom First check
Bot will not join Server auth/offline-mode assumptions.
Viewer blank Viewer port, chunk load, secure-profile mismatch.
Dashboard stuck Relay reachable? client syntax/runtime error?
Port collision PM2 vs systemd vs manual duplicate process.
Lag spikes Spark, bot count, JVM pressure.

Sources: wiki/content/docs/debugging.md, moincraft/docs/error-logging-and-debugging.md.