Symptoms:

• Players cannot connect to server
• "Failed to connect" or "Connection timed out" message appears
• Server shows in browser but connection fails
• Players can connect locally but not remotely

Solutions:

1. Check Port Forwarding: Ensure ports 16261 (default UDP) and 16262 (Steam query) are properly forwarded on your router.
2. Verify Firewall Settings: Add exceptions for Project Zomboid server executable in Windows Firewall or configure iptables on Linux.
3. Test Local Connection: Try connecting from a device on the same network to rule out internet issues.
4. Check Server Status: Verify the server process is running with netstat -tulpn | grep 16261 (Linux) or Resource Monitor (Windows).
5. Update Server Files: Ensure server is updated to latest stable version using SteamCMD.

Symptoms:

• Server doesn't appear in Project Zomboid server browser
• Direct IP connection works but browser doesn't show server
• Server visibility set to "Public" but not listed
• Intermittent visibility in browser

Solutions:

1. Enable Steam Query: Ensure SteamPort=16262 and SteamQueryPort=16262 are set in pzserver.ini.
2. Check Query Port: Verify port 16262 is open and accessible (used for Steam queries).
3. Wait for Registration: Steam server browser can take 5-15 minutes to register new servers.
4. Server Name Format: Avoid special characters in server name that might break browser listing.
5. Use Server Browser Commands: Try /refresh in server browser or restart game client.

Symptoms:

• Delayed player actions and zombie movements
• High ping for all connected players
• World saving causes temporary freezes
• Zombie pathfinding lag during horde events

Solutions:

1. Optimize Zombie Settings: Reduce ZombieCount or adjust distribution in sandbox settings.
2. Increase Memory Allocation: Add -Xmx4g (or higher) to server startup arguments for more RAM.
3. Reduce View Distance: Lower ViewDistance in server settings to reduce client-server sync load.
4. Schedule Regular Restarts: Daily server restarts clear memory leaks and improve performance.
5. Use Performance Mods: Consider mods like "Clean Dirt" or "Optimal Performance" for large servers.

Symptoms:

• Server process using excessive CPU (90%+)
• Memory usage constantly increasing over time
• Server becomes unresponsive after extended uptime
• Java garbage collection causing periodic lag spikes

Solutions:

1. Limit Player Count: Reduce MaxPlayers setting to match server capabilities.
2. Optimize Java Arguments: Use optimized JVM flags: -XX:+UseG1GC -XX:MaxGCPauseMillis=200.
3. Regular Restarts: Schedule daily server restarts to clear memory leaks.
4. Monitor with Tools: Use htop (Linux) or Process Explorer (Windows) to identify resource hogs.
5. Upgrade Hardware: Consider moving to dedicated hosting with better CPU/RAM resources.

Symptoms:

• World fails to load on server startup
• Characters or structures missing after server restart
• "Failed to load world" error message
• Map chunks not loading or appearing corrupted

Solutions:

1. Restore from Backup: Use Supercraft's automated backups or manual backup files in server-data/Saves/.
2. Verify File Permissions: Ensure server has write access to save directory.
3. Check Disk Space: Ensure adequate free space for world saves (minimum 2GB).
4. Use Map Fix Tools: Consider using "Project Zomboid Map Fix" tools for corrupted map files.
5. Prevent Corruption: Always use proper shutdown procedure (Stop button) rather than killing process.

Symptoms:

• Character items missing after server transfer
• Skills reset or decreased unexpectedly
• Character file corruption errors
• Duplicate characters appearing

Solutions:

1. Backup Character Files: Regularly backup players.db from server-data/db/ directory.
2. Check Database Integrity: Use SQLite browser to verify players.db isn't corrupted.
3. Avoid Cross-Server Transfers: Character files may not be compatible between different server modsets.
4. Manual Restoration: Replace corrupted character data with backups using SQLite tools.
5. Preventive Measures: Ensure consistent mod load order across server restarts.

Symptoms:

• Server crashes on startup with mods enabled
• Players cannot connect due to mod mismatch
• Game features broken after mod installation
• Inconsistent behavior between server and clients

Solutions:

1. Verify Mod Versions: Ensure all mods are updated to latest versions compatible with Project Zomboid version.
2. Check Load Order: Some mods require specific load order in server-data/Server/ mod list files.
3. Test Mods Individually: Disable all mods, then enable one at a time to identify conflicts.
4. Check Workshop IDs: Ensure server and clients subscribe to same Workshop IDs (not local mod files).
5. Use Mod Manager: Consider using mod managers for consistent deployment across server and clients.

Symptoms:

• Custom maps not loading on server
• Players missing map data when joining
• Map errors or missing textures
• Server-client map version mismatch

Solutions:

1. Verify Map Installation: Ensure map files are correctly placed in server-data/media/maps/.
2. Check Map Compatibility: Confirm map is compatible with current Project Zomboid build.
3. Client-Side Installation: Players may need to install map mods separately if not auto-downloaded.
4. Map File Permissions: Ensure server has read access to map files and directories.
5. Test Without Maps: Disable map mods temporarily to isolate issue.

Symptoms:

• Admin wrench icon not appearing in-game
• Admin commands not working
• Cannot access admin panel
• Admin permissions reset after server update

Solutions:

1. Check Admin Files: Verify username in pzserver_admin.txt (case-sensitive, exact Steam name).
2. Reset Admin Database: Delete pzserver.db in server-data/db/ to reset permissions (preserves player data).
3. Verify Steam Name: Ensure Steam profile name matches exactly what's in admin file.
4. Check File Permissions: Server must have write access to admin and database files.
5. Use Console Commands: If partial access, try /grantadmin "Username" via console (F11).

Detailed Guide: See our complete Restore Lost Admin Access guide for step-by-step solutions.

Symptoms:

• Banned players can still join
• Whitelist not working properly
• Ban list reset after server restart
• Cannot ban specific players

Solutions:

1. Check Database Integrity: Verify pzserver.db isn't corrupted using SQLite browser.
2. Use Steam IDs: Ban by Steam ID (64-bit) instead of username for more reliable bans.
3. Verify Whitelist Enable: Ensure Open=false in pzserver.ini and whitelist file populated.
4. File Permissions: Server needs write access to database for ban persistence.
5. Manual Database Edit: Use SQLite browser to directly edit ban list if needed.