Installing Steam Workshop mods on a Project Zomboid dedicated server trips up more first-time admins than anything else in servertest.ini. The reason is almost always the same: Project Zomboid uses a two-key system, and forgetting one of the two keys is the single most common mod failure. This guide walks through exactly how the system works, why both keys are mandatory, how load order behaves, and how to debug a mod that refuses to load. Everything here applies to the stable Build 41 (B41.78) branch and carries forward unchanged into the Build 42 unstable beta branch (opt-in since December 2024, still not the default stable build as of mid-2026).
The two-key system: WorkshopItems vs Mods
Adding a Workshop mod to a Project Zomboid server requires editing two separate keys inside your servertest.ini file. They do different jobs, and a mod only works when both are filled in correctly:
WorkshopItems=takes numeric Steam Workshop IDs — the number from the Workshop page URL. This tells the server what to download. Entries are semicolon-separated.Mods=takes internal text Mod IDs — identifiers baked inside each mod, not the display names you see on Steam. This tells the server what to activate. Entries are also semicolon-separated.
Think of it as a download list and an activation list. WorkshopItems fetches the package from Steam; Mods switches the contents on. If you fill in only WorkshopItems, the files download to disk but never load into the world. If you fill in only Mods, the game tries to activate something it never downloaded. Both keys are required, every time.
WorkshopItems=624489512;972954692;670807387
Mods=CraftableAxes;Katana;MREMeal;NecroForgeWorkshop ID vs Mod ID — the distinction that matters
These two identifiers are not interchangeable, and confusing them is what breaks most mod installs:
| Identifier | Where it lives | Format | Goes in |
|---|---|---|---|
| Workshop ID | The number at the end of the Steam Workshop URL (?id=624489512) | Numeric | WorkshopItems= |
| Mod ID | Inside the mod’s own files / on the Workshop description page | Text (e.g. CraftableAxes) | Mods= |
The crucial wrinkle: one Workshop item can contain several Mod IDs. A single Workshop package might bundle a weapons pack, a UI tweak, and a translation, each with its own internal Mod ID. In that case you list one Workshop ID under WorkshopItems but multiple Mod IDs under Mods. This is why the two lists frequently have different lengths — and why you can’t just copy the numbers across. Good mod authors publish the exact Mod ID(s) in the Workshop description; always read it rather than guessing.
Where to edit: the servertest.ini file
A Project Zomboid dedicated server is configured by files inside your Zomboid/Server/ folder. On Windows that’s C:\Users\. The default server name is servertest, so the files are named servertest*. Three (technically four) files matter:
servertest.ini— main server settings, including theWorkshopItemsandModskeys, networking/ports, player cap, PVP, passwords, map, spawn point and RCON.servertest_SandboxVars.lua— the world ruleset (zombie population, loot rates, XP multipliers, day length). Some mods add their ownSandboxVars.luaentries here rather than to the.ini.servertest_spawnregions.lua— the cities/regions offered on the spawn screen (PZwiki also lists aservertest_spawnpoints.lua).
The Workshop two-key system lives entirely in servertest.ini. If you want a full breakdown of every other setting in that file — PVP, MaxPlayers, passwords, the anti-cheat family — see our companion walkthrough on the servertest.ini settings explained. For the broader picture of standing a box up from scratch, our guide on creating a Project Zomboid dedicated server covers SteamCMD install and start scripts.
Step-by-step: adding a Workshop mod
1. Find the Workshop ID
Open the mod’s Steam Workshop page. The URL ends with ?id= followed by a number — that number is the Workshop ID. For example, in steamcommunity.com/sharedfiles/filedetails/?id=624489512 the Workshop ID is 624489512. Collect the IDs for every mod you want.
2. Find the Mod ID(s)
Most authors list the internal Mod ID directly on the Workshop description, often as a line like Mod ID: CraftableAxes. Remember a single package can expose more than one. If the description doesn’t state it, the Mod ID is the folder name inside the mod’s media/ structure once downloaded. Use the exact text identifier, not the human-readable title.
3. Edit servertest.ini
Stop the server first. Open servertest.ini in a plain-text editor and append your IDs to each key, separating entries with semicolons and no spaces. Adding a katana mod and a craftable-axes mod looks like this:
WorkshopItems=624489512;972954692
Mods=CraftableAxes;KatanaIf a single Workshop item bundles two activatable mods, you’d list one Workshop ID but two Mod IDs:
WorkshopItems=670807387
Mods=MREMeal;MREMeal_Translation4. Start the server — it auto-downloads
On startup the server automatically downloads every item listed in WorkshopItems straight from Steam — you do not pre-download anything manually. Watch the console (more on logs below) as it fetches each package, then activates the matching Mods entries. On a large mod list the first boot can take a while; subsequent boots only fetch updates.
Load order: left to right
Order matters in the Mods= line. Project Zomboid loads mods left to right, and later entries can override earlier ones. When two mods touch the same item, recipe, or script, the one further right in the list wins. The practical rules:
- Put framework/library mods first (left), since other mods depend on them being loaded already.
- Put patches and compatibility mods last (right), so their overrides take effect.
- If two mods conflict, experiment by swapping their order in
Mods=before assuming one is broken.
The order of WorkshopItems is just a download list and has no gameplay effect — only the order of Mods changes behavior.
The #1 gotcha: forgetting one key
By far the most common support ticket is “my mod downloaded but isn’t working” or “my mod won’t download.” Both symptoms come from filling in only one of the two keys. Run through this checklist whenever a mod misbehaves:
| Symptom | Likely cause | Fix |
|---|---|---|
| Files download but mod does nothing in-game | Workshop ID present, Mod ID missing from Mods= | Add the correct text Mod ID(s) to Mods= |
| Server complains the mod can’t be found | Mod ID present, Workshop ID missing from WorkshopItems= | Add the numeric Workshop ID to WorkshopItems= |
| One mod from a bundle works, another doesn’t | Bundle has multiple Mod IDs, only one listed | List every Mod ID the package exposes |
| Mods load but one overrides another wrongly | Wrong left-to-right order | Reorder entries in Mods= |
| Used the display name instead of the Mod ID | Display name ≠ internal Mod ID | Use the exact text Mod ID from the description |
A simple sanity rule: the number of distinct mods you intend to run should match the number of Mods= entries, and every Workshop package you want should appear once in WorkshopItems=. Counts won’t always be equal (because of bundles), but every active mod must trace back to a downloaded package.
Verifying and reloading without a full restart
Two admin commands help confirm your changes took effect. Run them in the server console without a slash, in in-game chat with a / prefix, or over RCON:
showoptions— prints the current.inisettings so you can confirm yourWorkshopItemsandModsvalues are actually loaded.reloadoptions— hot-reloadsservertest.iniwhile the server is running, applying many setting changes without a restart.
That said, adding or removing mods is best done with a full stop/start, because the server only auto-downloads new Workshop items during startup. Use reloadoptions for tweaks to existing settings, not for fetching a brand-new mod. For the full command set — access levels, item spawning, teleports, bans — see our Project Zomboid admin commands reference.
Debugging a mod that breaks the server
When a mod causes errors or a crash, the logs tell you which one. Live output goes to server-console.txt in your Zomboid/ folder (one level up from Server/) — that’s the startup sequence, mod-load output, and player connections. On restart, prior logs are moved into Zomboid/Logs/ and timestamped.
- Open the latest
*_DebugLog-server.txtfor Lua errors and crash stack traces — this is the best file for mod-related faults. A Mod ID near the error usually points straight at the culprit. - Confirm a clean boot in
server-console.txt(or*_coop-console.txtin the timestamped set) — look for each Workshop item downloading and each mod activating. - Once you’ve identified the offending mod, remove its entry from
Mods=(and optionallyWorkshopItems=) to disable it, then restart.
Our deeper walkthrough on how to check Project Zomboid server logs maps every log file (chat, PVP, safety/anti-cheat) to its purpose. If you’d rather skip the file-juggling entirely, a managed Project Zomboid server you can rent exposes the mod lists in a control-panel field and handles the Workshop downloads for you.
Build 41 vs Build 42: does anything change for mods?
Good news: the Workshop two-key system is identical across Build 41 and Build 42 in every source reviewed. The same WorkshopItems + Mods mechanism, the same Zomboid/Server/ layout, and the same admin commands carry over. What you do need to watch:
- Branch status (mid-2026): Build 41 (B41.78) is still the stable/default branch most servers run. Build 42 has been on the opt-in “unstable” branch since December 2024; the latest unstable release in our sources is Build 42.17.0 (~April 2026). Press calls stable “close,” but no confirmed stable ship date — don’t assume B42 is default.
- Multiplayer in B42: MP was absent at B42’s first launch and only joined the unstable branch around December 2025 (≈v42.13). Early B42 dedicated-server info from 2024 is unreliable for MP.
- Mod compatibility, not config: the config mechanism is unchanged, but individual mods must be authored for your build. B42 saves are not compatible with B41 and there’s no official converter, so don’t mix a mod list across builds expecting the same world.
- RAM: B42 is heavier — plan more headroom in your
-XmxJVM flag than a comparable B41 server. - New SandboxVars: B42 added animal, basement and darkness settings as
SandboxVars.luaentries (not new.inikeys), so mods touching those areas may expose extra options there.
When you run B42, always check a mod’s Workshop page to confirm it lists Build 42 support before adding it. For the official setup reference, see the Project Zomboid documentation.
When a mod corrupts a character (and how to recover safely)
Occasionally a removed or updated mod leaves one player with a broken character — items that no longer exist, a skill tree that won’t load. You can reset that single character without touching anyone else’s progress, but this edits a live database, so treat it as destructive and back up first.
Multiplayer saves live in Zomboid/Saves/Multiplayer/. Per-player data sits in the SQLite database players.db inside that folder, in the NetworkPlayers table (one row per character). To reset just one character:
- Stop the server and make a backup copy of
players.dbbefore doing anything else. - Open
players.dbin DB Browser for SQLite → Browse Data → tableNetworkPlayers. - Find the broken player’s row, select the whole row, delete only that one row, then Write Changes.
- Restart. The world, other players and all map data are untouched; that player simply recreates a fresh character on next join.
This zeroes the character — it cannot recover the pre-break state, and a wrong table or row deletion is permanent. The full procedure is in our guide on resetting a broken Project Zomboid character without affecting other players.
Frequently asked questions
Why did my mod download but not work?
Because you filled in WorkshopItems= (the download list) but left the matching internal Mod ID out of Mods= (the activation list). The files arrive on disk but never load. Add the exact text Mod ID — found on the Workshop description, not the display title — to Mods= and restart. This is the single most common Workshop mistake.
Where do I find a mod’s Mod ID versus its Workshop ID?
The Workshop ID is the number at the end of the Steam Workshop page URL (after ?id=) and goes in WorkshopItems=. The Mod ID is a text identifier the author publishes in the Workshop description (e.g. CraftableAxes) and goes in Mods=. One Workshop package can contain several Mod IDs, so always read the description — never assume the count matches.
Does the order of mods matter?
Yes, for the Mods= line. Project Zomboid loads mods left to right, and later entries can override earlier ones. Put libraries and frameworks first and patches/compatibility mods last. The order of WorkshopItems= is only a download queue and has no gameplay effect.
Do I have to download mods manually before adding them?
No. The server automatically downloads everything listed in WorkshopItems= directly from Steam on startup. You just edit the two keys in servertest.ini, stop and start the server, and watch the console fetch each package. New mods are pulled at boot, so add or remove mods with a full restart rather than a live reloadoptions.
Are mods the same on Build 42 as Build 41?
The two-key install mechanism is identical on both builds — same WorkshopItems/Mods keys, same file location. Individual mods, however, must be authored for your build, and B42 (the unstable beta branch as of mid-2026) saves aren’t compatible with B41. Always confirm a mod lists support for your build on its Workshop page, and budget extra RAM in your -Xmx flag for B42.
How do I tell which mod is crashing my server?
Open the latest *_DebugLog-server.txt in Zomboid/Logs/ — it holds Lua errors and crash stack traces, and a Mod ID near the error usually identifies the culprit. Confirm the boot sequence in server-console.txt. Once you know which mod is at fault, remove its entry from Mods= to disable it and restart.
Ready to play?
Run your own Project Zomboid server with XGamingServer
Spin up an always-on Project Zomboid server your friends can join in minutes — no port-forwarding, no tech headaches.
