Troubleshooting

Troubleshooting

← Home · Zurück: Monitoring-und-Alerts

Die Fehler-Enzyklopädie für den B42-Server: erst Schnelldiagnose, dann Symptom-Tabelle mit Ursache und Fix, darunter Vertiefungen für die großen Themen. Vollständig übernommen aus docs/07-troubleshooting.md und erweitert um die Fehlerbilder der verifizierten B42-Mini-Guides.

Label-Konvention: (Repo) = Verhalten/Skript 1:1 aus diesem Repo; (Community-Quelle: X) = extern belegt; (Heuristik) = begründete Empfehlung.

Schnelldiagnose (immer als Erstes)

Drei Befehle in dieser Reihenfolge:

make status       # systemctl-Status + Healthcheck (3 Prüfungen)
make healthcheck  # Healthcheck einzeln (Prozess, UDP-Port, Log-Scan)
make logs         # Live-Logs: journalctl -u zomboid -f

Was man dabei sieht:

• make status zeigt den systemd-Zustand (läuft/failed inkl. Restart-Zählern) und direkt darunter den Healthcheck — Prozess aktiv? UDP-Port gebunden? Kritische Log-Zeilen der letzten 5 Minuten (OutOfMemory, Exception in thread, FATAL)? (1:1 aus Makefile + healthcheck.sh; Details Monitoring-und-Alerts).
• make logs hängt am Journal: Startup-Sequenz, Mod-Ladung, Spieler-Connects, Save-Zyklen. Beim Live-Zusehen sieht man Fehler oft im Moment ihrer Entstehung.

Danach: Symptom in der Tabelle suchen, Fix anwenden, Sauberkeitshalber neu starten und prüfen, dass der Fehler nicht wiederkehrt (nur dann „behoben" — Heuristik der Mini-Guides).

Fehler-Enzyklopädie

Symptom	Ursache	Fix
Server startet nicht: Address already in use / Port belegt	Anderer Prozess auf 16261/16262	sudo ss -ulnp | grep 1626 → PID identifizieren, Dienst stoppen oder Port ändern (Repo-Diagnoseweg aus docs/07)
Server startet nicht: Skript bricht mit „.env fehlt" ab	.env existiert nicht	cp .env.example .env, Werte setzen (Guard need_env in lib/common.sh, Repo)
Server startet nicht: Rechte-Probleme unter /opt/pzserver	PZ_USER/Verzeichnisse falsch	PZ_USER/PZ_*_DIR in .env prüfen, make install erneut (idempotent) laufen lassen (Heuristik; Pfade: ENV-Variablen)
OutOfMemoryError im Log	RAM_XMX zu klein für Spielerzahl + Mods	RAM_XMX in .env erhöhen — Tiers und Faustformel in Performance-Guide; dann make restart (Repo docs/07 + Community-Tiers)
Abstürze unter Last (nach Stunden, bei Events)	Karten-Mods + NPC-artige Mods sind die größten Treiber	Modliste ausdünnen, Restart-Rhythmus prüfen (docs/07, Repo; Vertiefung Performance-Guide)
Spieler können nicht joinen: Verbindung timeout	Ports/Firewall — 16261 UND 16262 freigeben	sudo ss -ulnp | grep 1626 serverseitig; Router-Weiterleitung; Quellen-Konflikt: pzwiki listet beide als UDP, andere Recherche fand 16261 als TCP — Heuristik dieses Projekts: 16261 in BEIDEN Protokollen freigeben + 16262/udp (Community-Quellen, gelabelt; Details Ports-und-Netzwerk)
Spieler können nicht joinen: Passwort abgewiesen	SERVER_PASSWORD/ADMIN_PASSWORD falsch oder geändert	Werte in .env prüfen, ggf. neu rendern + Neustart (Repo; ENV-Variablen)
Server erscheint nicht in der Serverliste	Public=false (Template-Wert prüfen)	Server als Favorit über IP verbinden ODER Public=true rendern — Favorit ist der schnellere Weg (Heuristik; Options-Referenz Server-Konfiguration)
Workshop version mismatch beim Joinen	Client- und Server-Build/Mod-Stände weichen ab	Client: Steam → PZ → Eigenschaften → „Dateien auf Fehler pruefen"; Server: make update (zieht aktuelle Stände) (Repo docs/07)
Watchdog startet Server nicht neu	.planned-stop-Lockfile vergessen	rm .planned-stop im Repo-Verzeichnis, systemctl status zomboid prüfen (Repo docs/07; Flag-Referenz Monitoring-und-Alerts)
Discord-Notify kommt nicht an	DISCORD_WEBHOOK_URL leer	URL in .env setzen; Test: bash scripts/notify.sh "Test" "Hallo" (Repo docs/07)
Mods laden nicht / fehlen im Spiel (still)	Mods=-Zeile fehlt (nur WorkshopItems= gesetzt) oder falsche ID-Art	BEIDE Zeilen setzen: WorkshopItems= = Steam-Workshop-IDs, Mods= = Mod-IDs aus mod.info (nicht Anzeigename!). Repo-Lücke ehrlich: install/update laden keine Workshop-Items automatisch — Mod-Zeilen ggf. manuell aus der Generator-Ausgabe übernehmen, Download-Weg in SteamCMD-Referenz (Community-Quelle: PZ-Community-Doku; Repo-Stand)
Spawn-Region fehlt / Spieler spawnt falsch	Ordnernamen in spawnregions-Lua vs. Workshop-Ablage stimmen nicht überein	Regionen-Datei prüfen (Repo config/spawns/), make spawns neu generieren (Repo; Spawn-System)
Karte lädt fehlerhaft / Überschneidungen	Map=-Reihenfolge falsch	Semikolongetrennt, interne Ordnernamen, frühere Maps gewinnen, Muldraugh, KY IMMER zuletzt (Community-Quelle: Repo-Changelog 0.3.0; Mods-Referenz)
Assertion Failed: Illegal termination of worker thread beim Start	B41→B42-Migration / fehlende App-ID	steam_appid.txt im Server-Verzeichnis anlegen, Inhalt genau 108600. Repo-Lücke: install.sh legt die Datei NICHT an — manueller Schritt. Bei hartnäckigen Fällen: Stop, Backup, alten Zomboid-Ordner entfernen, neu starten (Community-Quelle: Steam-Diskussionen/pzwiki-Migrationsnotizen)
Update lief, Rollback hat gegriffen (Discord: „FEHLER - Rollback")	Healthcheck nach Update fehlgeschlagen → pre-update-Backup eingespielt	Save/Config-Stand ist wieder alt. Achtung: Rollback stellt NUR Saves/+Server/ zurück, NICHT die Server-Binärdateien (Repo update.sh 1:1). Vorgehen: Logs vom Update-Fenster prüfen (journalctl --since), Ursache fixen (oft Mods/Config), dann Update wiederholen; alte Serverversion gezielt einspielen wäre manueller SteamCMD-Weg (Heuristik; Updates-und-Rollback, SteamCMD-Referenz)
Disk full / Backups schlagen fehl	Backup-Verzeichnis voll (Retention greift nicht mehr / zu großes Archiv)	RETENTION_DAILY/RETENTION_WEEKLY in .env senken, altes Archiv manuell räumen; [Backup fehlerhaft] prüfen (Repo backup.sh: Rotation; Backup-und-Restore)
Erste Verbindung sehr langsam / „loading world" lange	Erster Boot: Weltgenerierung einer frischen Welt	Warten und Journal beobachten; nur bei Wiederholung auf bestehender Welt zum Storage-Kapitel (Heuristik; Performance-Guide)
ini-Änderungen zeigen keine Wirkung	Server läuft unter anderem -servername als die editierte Datei heißt	<servername>.ini muss exakt zum Startparameter passen; Log zeigt beim Start, welche ini geladen wurde (Community-Quelle: Mini-Guide 06; im Repo: Config aus Template rendern, nie von Hand — Server-Konfiguration)
Desync/Lags nur bei einem bestimmten Spieler	Client hat andere Modversionen/Load-Order	Client Rejoin; Load-Order abgleichen; serverseitig /checkModsNeedUpdate (Community-Quelle: Mini-Guide 06)
Steam zeigt „inkompatibel" trotz B42-Tag am Workshop-Item	Generische Steam-Warnung; Tag sagt nichts über echten Build	Mod-Beschreibung des Autors nach echtem B42-Tag durchsuchen, im Zweifel im eigenen Client testen (Heuristik: Mini-Guide 06; Mods-Referenz)

Vertiefungen

Server startet nicht

# Fehler der letzten Minuten greppen (wie der Healthcheck):
sudo journalctl -u zomboid --since "15 min ago" --no-pager | \
  grep -iE "OutOfMemory|Exception in thread|FATAL|ERROR"

# Wer belegt den Port? (UDP)
sudo ss -ulnp | grep 1626

# Unit-Zustand mit den letzten Meldungen:
systemctl status zomboid --no-pager

Typische Muster (Repo + docs/07): fehlende .env (Guard-Meldung der Skripte), Port belegt, Rechte auf /opt/pzserver/*, oder ein Mod verhindert den Start — dann: make validate (mods.yaml prüfen), letzten aktivierten Mod auf enabled: false, make mods, Retry; zur Not make restore auf das letzte pre-update-Backup (docs/07, 1:1).

Verbindungsprobleme

# Lauscht der Server wirklich? (UDP)
sudo ss -ulnp | grep 1626

# Vom Client aus testen — TCP-Seite:
nc -vz <server-ip> 16261
# UDP-Seite ergaenzend:
nc -vzu <server-ip> 16261

Hinweis (Heuristik, Mini-Guide 06): UDP-Connect-Tests sind unzuverlässig — Erfolg/Timeout sind nur ein Indiz; im Zweifel Firewall-Regeln und Router prüfen. Zusätzlich: Build-Gleichstand Client/Server und Passwörter prüfen, BEVOR Ports umkonfiguriert werden (docs/07). Protokoll-Konflikt 16261: Ports-und-Netzwerk.

Mods-Probleme

• Client-seitig console.txt auf fehlende IDs durchsehen (Community-Quelle: Mini-Guide 06).
• /showoptions als Admin zeigt, ob Optionswerte wirklich geladen wurden; /checkModsNeedUpdate prüft Mod-Stände (Community-Quelle: Mini-Guide 06 — exakte Admin-Befehle siehe dort; dieses Wiki erfindet keine Befehle).
• Struktur der beiden ini-Zeilen und Load-Order: Mods-Referenz; Workflow: Modding-Workflow.

Speicherprobleme und Abstuerze

# Angekommene Heap-Flags pruefen (Community-Quelle: EN-Guide, HotSpot-Standard):
ps -ef | grep -E 'java.*zomboid|ProjectZomboid' | grep -o -- '-Xm[sx][^ ]*'

# Heap-Snapshot:
jcmd <pid> GC.heap_info

# OutOfMemory-Frequency im Journal:
sudo journalctl -u zomboid --no-pager | grep -ci "OutOfMemory"

Einordnung (Community-Quelle + Repo-Doku): einmaliges OOM nach vielen Stunden → Restart-Rhythmus/Fragmentierung; sofortiges OOM nach Start → RAM_XMX zu klein für die Modliste. Skalierungsstufen und Faustformel: Performance-Guide Abschnitt 1. Achtung Versionssprung: B41-Werte gelten für B42 nicht (B42 ≈ +2 GB — Community-Beobachtung).

Watchdog- und Update-Verkettung

Der Watchdog läuft minütlich per Cron — wenn der Server „von selbst" wieder an ist, war es monitor.sh (Discord-Meldung „Server war abgestuerzt" prüfen; ohne Webhook: logs/server.log im Repo). Diagnosepfad (Repo):

# Lief der Watchdog? (Skript-Log)
grep -i "abgestuerzt\|DOWN" logs/server.log

# Was ist im Update-Fenster passiert? (Zeitpunkt anpassen)
sudo journalctl -u zomboid --since "2026-08-15 02:55" --until "2026-08-15 03:30" --no-pager

Bekannte Eigenheit (Repo-Stand, ehrlich): update.sh setzt kein .planned-stop — der minütliche Cron kann den Server im Stoppfenster hochziehen. Vor manuellen Updates: touch .planned-stop (Heuristik; Begründung in Monitoring-und-Alerts). Nach jedem Eingriff: Flag wieder entfernen, sonst greift der Watchdog nie wieder ein.

GCP-Failover startet nicht

# Bucket-Inhalt pruefen (gibt es ueberhaupt daily-Archive?):
gsutil ls "gs://${GCP_BUCKET}" | sort | tail -3

# Startup-Konsole der Instanz ansehen (GCP-Standard):
gcloud compute instances get-serial-port-output pz-failover --zone=europe-west3-a

Häufigste Ursachen (Repo-Stand): Platzhalter __GCP_BUCKET__/__REPO_URL__ im startup-script.sh wurden vor dem Anlegen nicht ersetzt; fehlende storage-rw-Scopes; leeren Bucket (sync-backups nie gelaufen). Details und Einrichtung: GCP-Failover.

Diagnose-Werkzeugkasten

Die wiederkehrenden Befehle dieses Wikis an einem Ort (Quellen: Repo-Skripte 1:1 bzw. gelabelte Community/Heuristik-Werte im jeweiligen Kapitel):

Frage	Befehl
Läuft der Prozess?	pgrep -f ProjectZomboid
Lauscht der UDP-Port?	sudo ss -ulnp | grep 1626
Kritische Log-Zeilen?	sudo journalctl -u zomboid --since "5 min ago" --no-pager | grep -iE "OutOfMemory|Exception in thread|FATAL"
Unit-Historie?	systemctl status zomboid --no-pager
Disk-Aktivität des JVM?	pidstat -d -p $(pgrep -fi zomboid) 2
Device-Latenz?	iostat -x 2
Platz auf dem Save-Device?	df -h /opt/pzserver
Skript-Eigenlog?	tail -50 logs/server.log (im Repo-Verzeichnis)

Systematik (Heuristik, aus den B42-Guides): pro Durchlauf genau eine Variable ändern, Weltzustand konstant halten, dieselbe Messung wiederholen — nur dann ist eine Verbesserung dem Fix zuordenbar. Und: Symptom nicht mit Ursache verwechseln — „illegal termination" ist ein Migrationsproblem, kein RAM-Problem; erst App-ID/Dateien prüfen, dann Hardware verdächtigen.

Wenn nichts hilft

1. Issue im Repo anlegen (CI-geprüftes Repo — Logs, Schritte, Config- Ausschnitt ohne Secrets beilegen; Heuristik).
2. Stand zurückrollen: make restore auf ein bekannt-gutes Backup — Ablauf und Snapshot-Vorher-Sicherung in Backup-und-Restore.
3. Notfallbetrieb: Hauptserver unbrauchbar → Failover auf GCP starten — GCP-Failover.

Verwandte Seiten

• Monitoring-und-Alerts — Healthcheck, Watchdog, Log-Rezepte
• Performance-Guide — Ruckler, OOM, IO-Symptome systematisch
• Updates-und-Rollback — Update-Zyklus und was der Rollback wirklich zurückholt
• Backup-und-Restore — interaktiver Restore
• Mods-Referenz / SteamCMD-Referenz — Mod-Zeilen, Workshop-Downloads
• Ports-und-Netzwerk — Port-/Protokoll-Grundlagen
• ENV-Variablen — alle Schrauben der .env

Vertieft in Repo: docs/07-troubleshooting.md.

---

Weiter: Konventionen-und-Quellen · Performance-Guide