Menu
  Log out
 

Server Logs

Project Zomboid Guide • Updated Jan 6, 2026

Server Logs and Error Troubleshooting

Server logs are your primary debugging tool when running a Project Zomboid server. Whether you're dealing with mod conflicts, configuration errors, or mysterious crashes, the logs hold the answers. This comprehensive guide covers where to find your logs, how to read them, and solutions to the most common errors you'll encounter.

When setting up a modded or customized server, misconfiguration is inevitable. Instead of guessing what went wrong, learning to read your server logs will transform you from struggling with errors to quickly diagnosing and fixing issues. This guide provides everything you need to become proficient at server troubleshooting.

Where to Find Server Logs

Method 1: Server Control Panel (Easiest)

Most server hosting control panels provide easy access to logs:

  1. Log into your server control panel
  2. Navigate to the Console or Logs tab
  3. View real-time server output and recent log entries
  4. Some panels allow downloading complete log files

Method 2: File Manager

Access logs directly through the file system:

Primary Log File: /server-data/server-console.txt

This file contains all console output including startup messages, errors, warnings, and runtime information.

Alternative Location: /home/container/.cache/server-console.txt

Some server configurations store logs in the cache directory instead.

Method 3: Direct File System Access (Advanced)

For self-hosted servers or advanced users:

Operating System Log Location Access Method
Windows %UserProfile%\Zomboid\Logs\ File Explorer → paste path in address bar
Linux ~/Zomboid/Logs/ or /home/linuxgsm/Zomboid/Logs/ Terminal or file browser
macOS ~/Zomboid/Logs/ Finder → Go to Folder

Additional Log Files:

  • console.txt - Client-side game log (for troubleshooting player issues)
  • DebugLog.txt - Detailed debugging information (same as server-console.txt for servers)
  • Zomboid-.txt - Archived logs from previous sessions

Customizing Log Location

You can change the cache folder (and thus log location) using the startup parameter:

-cachedir="C:\CustomPath\Zomboid"

If the folder doesn't exist, the server will create it automatically.

How to Read Server Logs

Understanding Log Structure

Project Zomboid logs follow a consistent format:

[12-28-25 14:32:15] [INFO] Server is starting
[12-28-25 14:32:16] [WARN] Mod "SomeModName" not found in Workshop
[12-28-25 14:32:17] [ERROR] Failed to load SandboxVars.lua

Components:

  • Timestamp - [12-28-25 14:32:15] - Date and time when the event occurred
  • Log Level - [INFO], [WARN], [ERROR] - Severity of the message
  • Message - Detailed information about what happened

Log Levels Explained

Level Meaning Action Required
[INFO] Informational message about normal operation None - just status updates
[WARN] Warning about potential issues Review - may cause problems later
[ERROR] Critical error that needs attention Must fix - causes server issues or crashes
[EXCEPTION] Java exception/crash Immediate attention - server may not function

Reading Strategies

Start from the Bottom: Recent events appear at the end of the log file. When troubleshooting, scroll to the bottom and work backwards to find the most recent errors.

Search for Keywords: Use Ctrl+F to search for:

  • "ERROR" - Find all error messages
  • "EXCEPTION" - Locate crashes and exceptions
  • "Workshop" - Check Steam Workshop mod issues
  • "Sandbox" - Find configuration problems
  • Specific mod names - Identify which mod is causing issues

Look for Patterns: If the same error repeats multiple times, that's likely your primary issue. Fix it first.

Common Server Errors and Solutions

1. Workshop Download Failures

Error Message:

Workshop: item state DownloadPending -> Fail ID=1234567890

What It Means: The server cannot download a Steam Workshop mod. The ID in the error message shows which mod is failing.

Solutions:

  1. Verify Workshop ID
    • Open pzserver.ini
    • Find the WorkshopItems= section
    • Check if the ID from the error message exists in the list
    • If the ID is invalid or typo'd, correct it
    • Remove the ID if you no longer want that mod
  2. Clear Workshop Cache
    • Navigate to SteamLibrary\steamapps\workshop\
    • Delete appworkshop_108600.acf
    • Restart the server (it will re-download mods)
  3. Delete Corrupted DLL Files
    • Go to steamapps\common\Project Zomboid Dedicated Server\
    • Delete all .dll files
    • Verify game files through Steam
    • Restart the server
  4. Run from Executable Directly
    • Instead of using Steam's shortcut, navigate to the install folder
    • Run ProjectZomboidServer.exe (Windows) or equivalent binary directly

2. SandboxVars Configuration Errors

Error Message:

Exiting due to errors loading /home/linuxgsm/Zomboid/Server/pzserver_SandboxVars.lua

What It Means: There's a syntax error in your SandboxVars.lua file, typically a missing comma, incorrect value, or typo.

Solutions:

  1. Check for Syntax Errors
    • Open /server-data/Saves/Multiplayer/YourServerName/pzserver_SandboxVars.lua
    • Look for red "x" marks or highlighting (if using an advanced editor)
    • Common issues: missing commas, missing quotes, incorrect booleans (use true not True)
  2. Validate Lua Syntax
    • Use an online Lua syntax checker
    • Or use a text editor with Lua support (VS Code, Notepad++)
    • Check that every setting line ends with a comma (except the last one)
  3. Common Syntax Mistakes: 
    -- WRONG:
Zombies = 3
Speed = 2

-- CORRECT:
Zombies = 3,
Speed = 2,
  4. Restore from Backup
    • If you can't find the error, restore from a backup
    • Or delete the file and regenerate it by starting the server

3. Map Configuration Errors

Error Message:

java.lang.IllegalStateException: Failed to find any .lotheader files

What It Means: The server cannot find the map you've configured, usually because the map name is incorrect or incomplete.

Solutions:

  1. Check Map Configuration
    • Open pzserver.ini
    • Find the Map= section
    • Ensure it ends with the correct format: Muldraugh, KY
  2. Common Map Names: 
    Map=Muldraugh, KY
Map=West Point, KY
Map=Riverside, KY
Map=Rosewood, KY
  3. For Modded Maps:
    • Verify the mod is installed and loaded before the map is set
    • Check mod documentation for the exact map name to use
    • Example: Map=RavenCreek, KY for Raven Creek mod

4. Mod Conflicts and Incompatibilities

Error Messages (Various):

[ERROR] Mod "ModName" requires "RequiredMod" which is not loaded
[WARN] Mod conflict detected between ModA and ModB
[EXCEPTION] NullPointerException in ModScript.lua

What It Means: Mods are conflicting with each other, missing dependencies, or incompatible with the current game version.

Solutions:

  1. Check Build Compatibility
    • Verify all mods support your server's Build (41 or 42)
    • Build 42 broke many mods - check Steam Workshop pages for updates
    • Remove or update incompatible mods
  2. Install Missing Dependencies
    • If the error mentions a required mod, install it
    • Example: Brita's Weapon Pack requires Arsenal GunFighter
    • Check mod descriptions for dependency lists
  3. Binary Search for Conflicts
    • Disable half your mods
    • If the error goes away, the problem is in the disabled half
    • Keep narrowing down until you find the conflicting mod
    • Remove or replace the problematic mod
  4. Check Load Order
    • Some mods must load before others
    • Adjust mod order in pzserver.ini (Mods= line)
    • Consult mod documentation for load order requirements

5. Permission Denied Errors (Linux/macOS)

Error Message:

java.io.IOException: Permission denied
Unable to write to Zomboid/console.txt

What It Means: The server doesn't have permission to write files to the Zomboid directory.

Solutions:

  1. Fix Directory Permissions 
    chmod -R 755 ~/Zomboid/
chown -R yourusername:yourusername ~/Zomboid/
  2. Check Directory is Not Read-Only
    • Right-click the Zomboid folder
    • Ensure it's not set to read-only
    • Grant write permissions to your user account
  3. Run with Appropriate User
    • Don't run the server as root unnecessarily
    • Use a dedicated server user with proper permissions

6. Port Already in Use

Error Message:

java.net.BindException: Address already in use
Failed to bind to port 16261

What It Means: Another program is using the port configured for your server.

Solutions:

  1. Find What's Using the Port

    Windows:

    netstat -ano | findstr :16261

    Linux:

    lsof -i :16261
  2. Stop the Other Program
    • Close any other Project Zomboid servers
    • Kill the process if it's stuck
  3. Change Server Port
    • Open pzserver.ini
    • Find DefaultPort=16261
    • Change to an unused port (e.g., 16262)
    • Update port forwarding rules if needed

7. Out of Memory Errors

Error Message:

java.lang.OutOfMemoryError: Java heap space
Exception in thread "main" java.lang.OutOfMemoryError: GC overhead limit exceeded

What It Means: The server ran out of RAM, typically from too many mods, players, or large maps.

Solutions:

  1. Increase Server RAM
    • Edit server start script or JVM arguments
    • Find -Xmx parameter (sets maximum heap)
    • Increase value: -Xmx4G for 4GB, -Xmx8G for 8GB
  2. Reduce Server Load
    • Remove unnecessary mods
    • Reduce maximum player count
    • Lower zombie population in sandbox settings
    • Use less demanding map mods
  3. Enable Garbage Collection Logging
    • Add JVM arg: -verbose:gc
    • Monitor memory usage patterns
    • Identify memory leaks from specific mods

8. Version Mismatch Errors

Error Message:

Workshop item version is different than the server's
Client version 41.78.16 does not match server version 41.78.15

What It Means: Client and server are running different game versions or mod versions.

Solutions:

  1. Update Server
    • Stop the server
    • Update via SteamCMD or your hosting panel
    • Verify all files are up to date
    • Restart the server
  2. Update Mods
    • Check for mod updates on Steam Workshop
    • Restart server to download latest versions
    • Verify mod versions match between server and clients
  3. Force Client Update
    • Players should verify game files through Steam
    • Unsubscribe and resubscribe to mods
    • Clear Workshop cache and redownload

9. Database Corruption

Error Message:

SQLException: database disk image is malformed
Failed to load player data

What It Means: The server's database (usually SQLite) has become corrupted.

Solutions:

  1. Restore from Backup
    • Stop the server
    • Restore database files from last known good backup
    • Restart and verify
  2. Repair Database (Advanced)
    • Use SQLite tools to attempt repair
    • Export data, rebuild database, reimport
    • This may result in some data loss
  3. Prevention
    • Enable automated backups
    • Don't kill server process forcefully (use graceful shutdown)
    • Ensure adequate disk space

10. First-Time Server Startup Messages

Message (Not an Error):

map_t.bin does not exist, cannot determine the server's WorldVersion

What It Means: This is normal the first time you start a server. The map files haven't been generated yet.

Action: None required - this is informational only. The server will generate necessary files on first run.

Log Analysis Methodology

Step-by-Step Troubleshooting Process

  1. Reproduce the Issue
    • Note exactly when the error occurs
    • Document what you were doing when it happened
    • Check if it's reproducible
  2. Access the Logs
    • Use control panel Console tab for real-time viewing
    • Or download server-console.txt for detailed analysis
  3. Find the Error
    • Scroll to the bottom (most recent events)
    • Search for [ERROR] or [EXCEPTION]
    • Note the timestamp matching when the issue occurred
  4. Read Context
    • Read 10-20 lines before the error
    • Look for warnings or related messages
    • Identify what the server was doing when it failed
  5. Search for Known Solutions
    • Copy the exact error message
    • Search this guide's common errors section
    • Google the error for community solutions
    • Check mod Steam Workshop pages for known issues
  6. Test the Fix
    • Implement the solution
    • Restart the server
    • Check logs to verify error is gone
    • Test functionality to ensure issue is resolved
  7. Document
    • Note what fixed the issue for future reference
    • Create backups after successful fixes
    • Update your server documentation

Preventive Maintenance

Best Practices to Avoid Errors

  • Regular Backups - Backup configuration files and world data daily
  • Test Configuration Changes - Never edit live servers without backups
  • Update Gradually - Update one mod at a time, test between updates
  • Monitor Logs Regularly - Check logs weekly even if no errors are apparent
  • Keep Mods Updated - But wait for stability reports before updating critical mods
  • Document Changes - Maintain a changelog of what you've modified
  • Use Version Control - Keep old versions of config files for rollback

Log Rotation and Management

Logs can grow very large over time:

  • Archive Old Logs - Move logs older than 30 days to archive folder
  • Compress Archives - Zip old logs to save disk space
  • Delete Ancient Logs - Remove logs older than 6 months unless needed
  • Monitor Disk Space - Ensure logs don't fill up your server drive

Advanced Debugging

Enable Verbose Logging

For difficult issues, enable more detailed logging:

  1. Add startup parameter: -debug
  2. Edit pzserver.ini, set DebugMode=true
  3. Restart server with debug enabled
  4. Reproduce the issue
  5. Check logs for additional detail
  6. Disable debug mode after troubleshooting (impacts performance)

Java Stack Traces

When you see exceptions with stack traces:

[ERROR] Exception in thread "main"
java.lang.NullPointerException
    at zombie.network.Server.init(Server.java:123)
    at zombie.GameServer.main(GameServer.java:45)

How to Read:

  • First line shows exception type (NullPointerException)
  • Following lines show code path that led to error
  • Top line is where error occurred
  • Lines below show function calls leading to the error
  • Look for mod names in the stack trace to identify culprit

Frequently Asked Questions

Q: How often should I check server logs?

A: Check logs whenever you experience issues, and review them weekly for warnings even if everything seems fine. Many issues start as warnings before becoming critical errors.

Q: Can I delete old log files?

A: Yes, but archive them first in case you need to reference historical data. You can safely delete logs older than 30-60 days unless investigating long-term issues.

Q: The console tab is blank - where are my logs?

A: If the control panel console is empty, access logs via File Manager at /server-data/server-console.txt or check /.cache/server-console.txt depending on your hosting configuration.

Q: Are [WARN] messages serious?

A: Warnings indicate potential issues but don't necessarily cause immediate problems. However, accumulating warnings often lead to errors later, so address them when possible.

Q: How do I share logs for support?

A: Use a paste service like Pastebin.com or GitHub Gist. Copy the last 100-200 lines of the log (including the error) and share the link with support staff.

Q: My log file is huge - how do I read it?

A: Download the file and open it in a text editor that supports large files (Notepad++, Sublime Text, VS Code). Search for [ERROR] to jump to relevant sections.

Q: Can mods write to logs?

A: Yes, mods can output log messages. Look for mod names in the log output to identify which mod is generating specific messages.

Q: What does "Workshop general failure" mean?

A: This indicates Steam Workshop download issues. Solutions include clearing Workshop cache, verifying server files, and ensuring your server has proper Steam integration.

Related Guides

Conclusion

Server logs are your best friend when troubleshooting Project Zomboid servers. By learning to locate, read, and interpret log messages, you can quickly diagnose and fix issues that would otherwise be mysterious black boxes. The common errors in this guide cover 90% of problems you'll encounter, especially on modded servers.

Remember the key principles: always check logs when issues arise, read error context (not just the error line), search for known solutions before experimenting, and maintain regular backups so you can rollback failed changes. With practice, you'll go from confused by errors to confidently fixing them in minutes.

Bookmark this guide and refer to it whenever you encounter new errors. As you gain experience, you'll develop intuition for what certain error patterns mean and where to look for solutions. Happy troubleshooting!

← Back to Project Zomboid Guides
Top