Project Zomboid Server Won't Start: 5-Step Checklist

Project Zomboid Server Won't Start: The 5-Step Checklist

"Server won't start" is the most common Project Zomboid hosting ticket and the most ambiguous. The phrase covers four very different failures: a workshop mod with a typo in its ID, a broken SandboxVars file, a corrupted map cell, and a JVM that ran out of RAM. Each has a distinct fingerprint in the logs and a distinct fix.

Walk the checklist in order. Stop at the first step that matches. Each step has the signature to look for and the fix.

Where to look

On a Supercraft node every PZ server stores its boot output in the same place. Paths below are relative to the server's root directory (what you see when you connect via FTP):

prz/process-control/stdout.log    # game stdout (usually empty on a fatal boot error)
prz/process-control/stderr.log    # the actual Java stack traces
Zomboid/Logs/                     # gameplay + console logs, rotated per run
Zomboid/Server/servertest_*.ini   # server config
Zomboid/Server/servertest_SandboxVars.lua   # sandbox settings (Lua)

The first place to read is always stderr.log. Empty stdout with the panel flipping back to offline almost always means a Java exception landed in stderr.

Step 1: Workshop mod ID typos

Signature: server starts, then exits a few seconds in. Stack trace in stderr includes references to zombie.WorkshopManager or the log notes a workshop item that "failed to subscribe".

PZ has two parallel mod settings in servertest.ini:

Mods=ModName1;ModName2;ModName3
WorkshopItems=2169435993;2392709985;2685168362

Mods is a list of mod folder names. WorkshopItems is a list of Steam Workshop numeric IDs. The two must match: every mod folder in Mods= must come from a workshop ID in WorkshopItems= (unless the mod is shipped manually).

A single trailing semicolon, a swapped order, or a wrong workshop ID is enough to fail the boot. Fix: open the workshop pages, copy each numeric ID and each folder name fresh, paste them in matching order. Restart.

Step 2: SandboxVars.lua syntax

Signature: stderr shows a Lua parse error referencing a line number in servertest_SandboxVars.lua. Common culprits are a missing trailing comma, a mismatched { }, or a value that should be a number written as a string.

The file is real Lua, not JSON. The most common shape is:

SandboxVars = {
    Zombies = 3,
    Distribution = 1,
    DayLength = 2,
    StartYear = 1,
    StartMonth = 7,
    -- ... etc
}

Fix: always edit a copy first. Paste your edited file into any online Lua linter (lua-fmt, the online Lua REPL, or just luac -p file.lua if you have Lua installed) before restarting the server. The error message tells you the line; the bug is almost always within two lines of where Lua complained.

Step 3: map_meta.bin corruption after a workshop update

Signature: stderr contains a Java stack trace from IsoMetaGrid.load and lines like:

Stack trace:
  zombie.core.properties.IsoPropertyType.lookup(IsoPropertyType.java:269)
  zombie.core.TilePropertyAliasMap.register(TilePropertyAliasMap.java:54)
  zombie.iso.IsoWorld.GenerateTilePropertyLookupTables(IsoWorld.java:1304)
  zombie.iso.IsoWorld.init(IsoWorld.java:2168)
  zombie.network.GameServer.main(GameServer.java:802)
ERROR: Lua    > ERROR: Mannequin zone missing properties
  in media/maps/<MapName>/objects.lua coords: 13583, 1299, 0
ERROR: General > invalid room metaID #231 in cell 25,33 while reading map_meta.bin

This is the fingerprint of a map mod that updated and re-numbered its room metadata while your save still references the old IDs. The save is intact, the world is intact, but the cell index can no longer be parsed.

Fix in order of preference:

1. Roll back the map mod to the version your save was created on (Steam Workshop history, or grab a snapshot from a backup). This is the only path that preserves the existing world.
2. Reset the affected cells. The wiki article reset parts of map covers per-cell resets. The mannequin/zone errors usually point at one or two cells.
3. Start a fresh world. If the corruption spans many cells or the mod author removed old assets, a new world is faster than chasing each cell.

The official PZ forum thread "Invalid Room ID in cell # - Map_meta.bin" documents this same pattern across multiple builds.

Step 4: JVM RAM ceiling

Signature: stderr shows java.lang.OutOfMemoryError: Java heap space or the server exits with signal 9 (kernel OOM kill) before producing any Java output.

PZ's JVM is configured in ProjectZomboid64.json:

{
    "mainClass": "zombie.gameStates.MainScreenState",
    "vmArgs": [
        "-Xms4g",
        "-Xmx8g",
        ...
    ]
}

-Xmx is the ceiling. With heavy map mods (Bedford Falls + Raven Creek + a dozen QoL mods) PZ commonly needs 8–12 GB at the JVM. Fix: raise -Xmx to a value at least 2 GB below the host RAM your plan provides. On Supercraft the per-deployment ceiling is set from the panel.

The companion wiki page allocate RAM walks through this in detail.

Step 5: Lock files from a previous run

Signature: stderr complains about a port already in use, or a file lock under ~/Zomboid/Server/ that cannot be acquired. The server then exits.

This happens when a previous shutdown left orphan lock files because the process was killed (OOM, manual kill, host reboot). The PZ launcher's own check writes a startup file that is never cleaned up.

Fix: stop the deployment from the panel, wait until it is fully offline, then check that no *.lock or stale PID file remains under ~/Zomboid/Server/ and the deployment's process-control/pidfile. The panel restart cycle handles this automatically; only intervene if it does not.

What the panel can show you, without SSH

The fast path

On Supercraft Project Zomboid hosting the workshop ID list, SandboxVars editor, and RAM ceiling all live in the panel, and stderr.log is tailed live in the console pane. If you are walking this checklist on a host that hides stderr, you are walking it blind: the table above only works if you can read the Java trace.