Project Zomboid Server Troubleshooting

Project Zomboid Server Troubleshooting

---

Players Can't Connect

Version mismatch — most common cause: The server and client must be on the same game version. Update the server:

~/steamcmd/steamcmd.sh \
  +force_install_dir /home/steam/pz \
  +login anonymous \
  +app_update 380870 validate \
  +quit

Wrong password: Verify the join password in servertest.ini:

Password=

Leave blank for no password.

Firewall blocking ports: Ensure UDP 16261 and 16262 are open:

sudo ufw allow 16261/udp && sudo ufw allow 16262/udp
sudo ufw status

---

Server Not Appearing in Server Browser

Project Zomboid uses a public server list. If your server isn't showing:

1. Confirm PublicServer=true in servertest.ini
2. Confirm both UDP ports (16261 and 16262) are open and forwarded
3. The browser can take a few minutes to list a newly started server
4. Players can use Direct Connect with your IP and port 16261 as a workaround

---

Mod Loading Failures

"Mod X not found" on startup:

• Confirm the mod name in Mods= exactly matches the id= field in the mod's mod.info
• Names are case-sensitive
• Ensure the Workshop ID in WorkshopItems= is correct

Server crashes after adding mods: Add mods one at a time with restarts in between to isolate the problem mod. Check logs at ~/.local/share/ProjectZomboid/Logs/ for the error.

Players can't join modded server: All players need the same mods. The game shows which mods are required in the server browser description and the connection error message.

---

"Failed to Create World" / Blank Save

This typically means the save directory has incorrect permissions:

chown -R pzserver:pzserver ~/.local/share/ProjectZomboid/
chmod -R 750 ~/.local/share/ProjectZomboid/

---

High Latency / Poor Performance

Reduce online player limit:

MaxPlayers=16

Reduce zombie density in servertest_SandboxVars.lua:

Zombies = 5,  -- Low population

Check Java memory usage: Project Zomboid uses Java. If the JVM is running out of heap:

# Edit JVM options in start-server.sh
-Xms2048m -Xmx4096m

---

Server Keeps Crashing

Check the server log at:

~/.local/share/ProjectZomboid/Logs/

Common causes:

• Out of memory: Increase JVM heap with -Xmx4096m
• Mod conflict: Remove mods one at a time to isolate
• Corrupted save: Restore from backup or delete the save and start fresh

---

Admin Password Lost

If you've forgotten the admin password, delete the server database file (this also deletes all bans and player data):

rm ~/.local/share/ProjectZomboid/db/servertest.db

Restart the server and set a new admin password at the first-run prompt.

---

"Steam Authentication Failed"

The server validates players through Steam. Ensure:

1. The server itself can reach Steam (outbound internet access)
2. Steam is not down (check status.steampowered.com)
3. SteamVAC=true is not accidentally set with incompatible settings

To temporarily bypass Steam auth for testing (not recommended for public servers):

PublicServer=false