Error Logging & Debugging

🐞 Error Logging & Debugging#

Minecraft Server (Paper)#

Structured Logging (JSON)#

File: log4j2.xml in server root:

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="WARN" packages="com.mojang.util">
  <Appenders>
    <Console name="SysOut" target="SYSTEM_OUT">
      <JsonTemplateLayout eventTemplateUri="classpath:LogstashJsonEventLayoutV1.json"/>
    </Console>
    <RollingRandomAccessFile name="File" fileName="logs/latest.log"
        filePattern="logs/%d{yyyy-MM-dd}-%i.log.gz">
      <PatternLayout pattern="[%d{HH:mm:ss}] [%t/%level]: %msg%n" />
      <Policies>
        <TimeBasedTriggeringPolicy />
        <OnStartupTriggeringPolicy />
      </Policies>
    </RollingRandomAccessFile>
  </Appenders>
  <Loggers>
    <Root level="info">
      <AppenderRef ref="SysOut"/>
      <AppenderRef ref="File"/>
    </Root>
  </Loggers>
</Configuration>

Crash Reports#

Location: ./crash-reports/
Key fields: Description, Stacktrace (look for Caused by:)

Timings & Spark#

/spark profiler --timeout 120

Look for “Lag Spikes” in the web view.

Mineflayer Bots (Node.js)#

Chrome DevTools Inspector (God Mode)#

node --inspect src/main.js
# Open chrome://inspect in Chrome

Features: Breakpoints, Variable Inspection, Console.

Memory Leaks#

const v8 = require('v8');
if (command === '!dump') {
  const fileName = `./heap-${Date.now()}.heapsnapshot`;
  v8.writeHeapSnapshot(fileName);
}

Analyze .heapsnapshot in Chrome DevTools “Memory” tab. Compare two snapshots to see what grew.

PM2 Log Rotation#

pm2 install pm2-logrotate
pm2 set pm2-logrotate:max_size 50M
pm2 set pm2-logrotate:retain 10
pm2 set pm2-logrotate:compress true

Dashboard (Svelte 5 / Vite)#

Server-Side Debugging (VS Code)#

Ctrl+Shift+P → “Debug: JavaScript Debug Terminal”
Run npm run dev
Set breakpoints in +page.server.js or hooks.server.js
Refresh browser — VS Code will pause execution

Network Debugging#

Browser: Network Tab → WS (WebSockets). Click connection to see raw frames
Server: DEBUG=socket.io* node src/index.js (see ALL socket traffic)

System (Linux)#

Journalctl (Systemd)#

journalctl -u moincraft.service -f          # Follow service logs
journalctl -p err --since "yesterday"       # Errors only, since yesterday

Disk Space Emergency#

find /var/log -type f -size +100M            # Find large files
truncate -s 0 /path/to/massive.log           # Truncate without deleting

Common Issues#

Symptom	Cause	Fix
Bot won’t join	`online-mode=true`	Set `online-mode=false` in server.properties
Viewer blank	Port not open / `enforce-secure-profile=true`	Open port 55669, set profile=false
Dashboard “Connecting…” forever	Syntax error in socket-client.js	Fix `let is Connected` → `let isConnected`
EADDRINUSE	Double orchestrator (systemd + PM2)	Disable one, never run both
Lag spikes	GC pressure, too many bots	Check `monitor.sh`, reduce bot count, tune JVM