How to Add Steam Workshop Mods and Map Mods to a Project Zomboid Server
Workshop mods and custom maps need three different IDs in three different lines, and Build 42 adds its own folder rules. Here is where each ID comes from, how map load order works, and how to add mods to a live world without breaking it.
The number from the Steam Workshop page URL. It goes in WorkshopItems= so the server knows what to download.
The id= value from the mod’s mod.info. It goes in Mods= so the game actually enables it.
Custom maps also need their folder names in Map=. One Workshop item can contain several map folders, not just one.
B42-ready mods normally include a common/ folder and a 42/ folder. If the item is B41-only, it usually will not load on a B42 server.
Start by checking you are editing the right server
A surprising number of “mods are not loading” reports turn out to be the wrong config set, the wrong save, or the wrong game build. Project Zomboid’s dedicated server uses a named server profile. If you start with -servername NAME, that name decides which .ini, save folder and databases are live. If you do not set one, the default is servertest.
For a standard server name, the files you usually care about are in C:\Users\<you>\Zomboid\Server on Windows or ~/Zomboid/Server on Linux: servertest.ini, servertest_SandboxVars.lua, servertest_spawnpoints.lua and servertest_spawnregions.lua. The world save sits in Zomboid/Saves/Multiplayer/servertest. Account and whitelist data are in Zomboid/db/servertest.db, while character data live in players.db inside the save folder.
When something goes wrong, check server-console.txt in the Zomboid folder first. That is where you will see failed Workshop downloads, mods that were not parsed, map errors, checksum kicks and version complaints. The player-side log is console.txt. If you are still setting the dedicated server up, or moving from a local Host save to a proper server install, use our dedicated server setup guide first so you are not chasing a mod issue that is really a setup issue.
One more sanity check: make sure players are joining the correct instance and port. The default game port is UDP 16261, with UDP 16262 used for direct connection, and each extra instance on the same machine needs two more UDP ports. If someone connects to an old instance, it looks exactly like the server ignored your new mod list.
The three identifiers you must match properly
Think of the server as doing three separate jobs. First, Steam downloads Workshop items. Second, the game enables internal mod packages. Third, the map system mounts world folders in a specific order. Those are different systems, so they use different identifiers.
- Workshop ID: the number in the Workshop page URL. Put it in
WorkshopItems=. - Mod ID: the
id=line inside that mod’smod.info. Put it inMods=. - Map folder name: the custom map’s folder name. Put it in
Map=.
One Workshop item can contain several Mod IDs and several map folders. That is the trap. If you add the Workshop ID but only copy one internal Mod ID, the server may download the pack yet only enable part of it. With map packs, copying only one folder name can leave required sub-maps unloaded, which is how you end up with missing roads, mismatched cells or clients kicked on join.
Where to find each one without third-party tools
- Workshop ID: open the item’s Workshop page and read the number in the page URL.
- Mod ID: check the mod author’s description first, then verify it in the downloaded files under
steamapps/workshop/content/108600/<WorkshopID>. - Map folder name: many authors list it in the description; if not, inspect the downloaded item and use the actual folder name the map mod provides.
The authoritative source for a mod package is its mod.info. That file is what the game reads when it decides what Mods= entries are valid.
An example mod.info excerpt (example names):
name=Example Mod id=ExampleMod description=Example only
Add Workshop mods to the server config the safe way
In servertest.ini, WorkshopItems= and Mods= work together. WorkshopItems= tells the server’s Steam side what to fetch. Mods= tells the game which internal packages to turn on at startup. If the Workshop item downloads successfully but its Mod ID is missing from Mods=, the content sits on disk and never becomes active.
The most reliable approach on Build 42 is to let the in-game Host Workshop settings or your host panel write the Mods= line, then verify the result in server-console.txt. During Build 42 Unstable, some versions required a backslash before each mod ID. Guidance varies by build and panel now, so manual editing can fail purely because the parser expects slightly different formatting. If you hand-edit it anyway, copy the exact Mod IDs from mod.info, match your panel’s format, and restart the server so the game re-reads the mod list from a clean boot.
Here is a minimal servertest.ini excerpt using obviously generic examples:
WorkshopItems=1234567890;2345678901 Mods=ExampleMod;ExampleDependency;ExampleMapCore Map=ExampleTownNorth;ExampleTownSouth;Muldraugh, KY
On builds and panels that use the backslash form, the same mod line reads Mods=\ExampleMod;\ExampleDependency;\ExampleMapCore. Whichever form your server writes, the IDs themselves are identical.
Use showoptions to check what the server currently thinks its active values are. Some .ini changes can be applied with reloadoptions, but for mod and map changes you should plan on a full restart. That forces the server to finish Workshop updates, rebuild script state and mount maps in the correct order, instead of trying to change live state halfway through a session.
Build 42 compatibility and legacy41 notes
Build 42 stable is not the same environment as legacy41. The server and every client must be on the same build, and old B41 saves are not compatible with B42. If your group is still on Build 41, clients switch in Steam under Properties, Game Versions & Betas, then choose legacy41; current stable uses no beta branch. If you are moving an older server forward, read the Build 42 migration guide before you import anything.
A simple way to judge B42 readiness is the mod’s folder structure. Build 42 mods commonly use a shared common/ folder plus a version-specific 42/ folder with its own mod.info. Older B41-only mods usually lack that 42 folder, so the server has nothing valid to load for B42.
steamapps/workshop/content/108600/1234567890/
└─ mods/
└─ ExampleMod/
├─ common/
│ └─ ...
└─ 42/
├─ mod.info
└─ ... Why this matters: the game is not just checking names, it is loading version-specific scripts, definitions and media. A B41-only package can download perfectly well and still fail at the next stage because the B42 loader does not find the structure it expects. The usual symptom is a mod that appears present on disk but never becomes active in the server log.
If an older server throws Assertion Failed: Illegal termination of worker thread during a B41 to B42 move, check that steam_appid.txt contains only 108600. After backing up, removing the old Zomboid user folder can also clear stale state carried over from a previous branch. Build 42.21 also added a notification when a player connects on a different game version, which helps separate version mismatches from mod mismatches.
Map mods need their own load order
Custom maps are the part most admins misconfigure, because a map mod is not enabled by Mods= alone. Its folder name must also be present in Map=, and the order matters. Project Zomboid reads that map list from top to bottom; where maps overlap, later entries overwrite earlier ones. Muldraugh, KY should be last.
Look at the order as a stack of world definitions. The server builds cell data from that stack, so a bad order can make one map paint over another, or let the vanilla map overwrite part of a custom region.
A generic example looks like this:
Map=ExampleOutskirts;ExampleCityCentre;Muldraugh, KY
- If a Workshop item contains more than one map folder, include all of them in
Map=, not just the headline name. - Keep dependencies and sub-maps in the order the author expects.
- Do not expect changing
Map=to rewrite already explored chunks in an existing save.
That last point matters. Once a chunk has been generated and saved, the save file takes priority over the map definition. So a corrected map order usually helps in unexplored areas first. If players have already travelled or built in the affected area, the old chunk data may remain until you restore a backup or deliberately wipe that part of the world.
Adding mods to an existing world safely
Always back up before you add or remove mods from a live save. Adding is usually safer than removing, but neither is risk-free. A map pack can change what future unexplored chunks look like; an item or tile mod can change what definitions the save expects to exist when it loads a cell, an inventory or a placed object.
At minimum, back up the world folder, the databases and the server config together: Zomboid/Saves/Multiplayer/servertest, Zomboid/db/servertest.db, and the matching files from the Server folder. Include the .ini because ResetID and ServerPlayerID live there; if they change, players are forced to create new characters. If you want a step-by-step process, use our backup and restore guide.
Project Zomboid also has built-in backups controlled in servertest.ini: startup backups, version-change backups and optional periodic backups. They are written to Zomboid/backups as zip files on the same disk as the world itself. That is useful for bad mod edits, but not enough protection against a disk problem because both the live save and the backup sit on the same storage.
What is usually safe, and what is not
- Adding item or vehicle mods: often fine if dependencies are correct.
- Adding map mods to unexplored areas: often fine, because new chunks can generate from the new map data.
- Removing item mods: risky, because containers, inventories and scripts may reference now-missing items.
- Removing tile or map mods: very risky, because saved chunks can reference now-missing tiles, textures or map data.
The rule is simple: if the save already contains something from that mod, removing the mod can leave broken references behind. That is why “it boots” is not the same as “it is safe”. Walk the affected area, log in with a test account, and check containers, recipes and map cells before you reopen the server fully.
Troubleshooting mods not loading, mismatch kicks and missing maps
Use the log before you start randomly deleting lines. Most failures fit a small set of patterns, and the fastest way to fix them is to match the symptom to the right stage: download, enable, map mount or client checksum.
| Symptom | Likely cause | First fix |
|---|---|---|
| Workshop item downloads but nothing changes in game | Workshop ID present, Mod ID missing or wrong | Open the item’s mod.info, copy every required id=, add them to Mods=, restart and recheck server-console.txt |
| Custom map content is missing or partly vanilla | Map folder not in Map=, or map order is wrong | Add the exact map folder names, put Muldraugh, KY last, and test in unexplored areas |
| Build 42 server says a mod failed to load | B41-only mod, or wrong branch on server or clients | Check for a 42/ folder and make sure everyone is on the same build |
DoLuaChecksum kicks on join | Real Lua mismatch or a false positive, especially on Linux hosts | Set DoLuaChecksum=false, restart, and see if the kick disappears |
| “File doesn’t exist on client” | Common B42 checksum or cache issue | Try DoLuaChecksum=false, then clear the client’s per-server downloaded data and reconnect |
| Only some players fail to join after a branch change | Client game version differs from the server | Confirm everyone is on the same branch and build, then reconnect |
Players cannot join an Open=false server | Steam ID not added | Add them with /addsteamid <steam_id> and retry |
| Players are prompted to make new characters | ResetID or ServerPlayerID changed in the config | Restore the backed-up .ini that matches the save |
disable half, test, keep narrowing.
Why turning off DoLuaChecksum can work
DoLuaChecksum=true makes the server compare client Lua files against the server’s copies and kick on mismatch. That is useful when you want strict script matching, but it can also produce false positives, especially on Linux hosts, and Build 42 “File doesn’t exist on client” errors are commonly resolved by setting it to false. Mechanically, you are telling the server to stop treating those file comparisons as a hard gate to joining.
The trade-off is straightforward: fewer false kicks, but less strict protection against client-side Lua differences. You will know it helped if the same player can now join cleanly and the server log stops printing checksum-related rejects.
If one mod breaks everything, bisect the list
Bisecting is the fastest clean method for a long mod list. Disable half the mods, test, then keep halving the failing side until you find the bad item or bad combination. This works because it cuts the search space aggressively instead of making you test mods one by one.
When clients keep getting odd file errors after the server list is fixed, remember that they store downloaded map data per server under an ip_port-named folder. Clearing the affected server’s cached data forces a fresh download from the corrected server config. You will know the fix worked when the join completes and the client no longer requests missing files from the old cache.
Tune it or upgrade: when mod problems are really resource problems
Not every bad mod experience is a bad mod. Some lists are simply too heavy for the available CPU time, Java heap or storage behaviour. Project Zomboid does a lot of work on the main simulation thread, and modded servers add more scripts, more definitions, more map data and longer startup processing. If players spread across several towns, the server keeps several areas loaded and simulated at once, which raises CPU work and memory pressure. Population growth over time adds to that as the world matures.
Memory is the first thing to size properly. The server heap is controlled by -Xms and -Xmx: in StartServer64.bat on Windows, or in ProjectZomboid64.json under vmArgs on Linux. The Windows batch file ships with 16 GB set, so it must be edited to fit the actual machine or it can fail to start with memory errors. The in-game Host menu’s Server Memory setting is the same idea, and the launch arguments use the ZGC garbage collector. As a rule of thumb, server operators usually keep heap around 70-80% of the plan’s RAM so Java still has room outside the heap; our Project Zomboid server RAM guide explains why that headroom matters.
| What you see | What the server is actually doing | Tune first | Upgrade when |
|---|---|---|---|
| Everyone gets periodic stutters that worsen as the world grows | The Java heap is too small, so garbage collection runs constantly | Raise -Xmx within safe headroom, trim bloated mods, reduce world pressure, restart cleanly | You cannot give the heap more room without risking the machine limit or the process being killed |
| Lag spikes mainly when players split across distant towns | The main thread is simulating several loaded areas at once | Cut script-heavy mods, review sandbox pressure, keep map additions sensible | A cleaned-up list still struggles during normal play with your regular group spread out |
| Random crashes or no clean save under load | The process is too close to the machine or plan limit, including memory outside the heap | Lower heap slightly, leave headroom, reduce concurrent world pressure | You need more total RAM than the current plan can safely provide |
The key is to tell resource exhaustion apart from config mistakes. A fixed config issue shows up immediately in the log: wrong ID, missing map folder, bad branch. A resource issue shows up in behaviour: longer stalls, worse garbage collection, or problems that grow with world age and player spread. If you are chasing server-side hitching as well as mod faults, use our Project Zomboid server lag guide.
If you are buying or resizing a plan, our Project Zomboid server hosting comparison treats 8 GB as the practical floor for Build 42, with more headroom sensible once you move past a small group or start stacking mods and custom maps.
If the IDs are right, the map order is right and the log is clean, persistent stutters or memory problems are usually a plan-sizing issue rather than a Workshop issue. Compare sensible options before you start cutting mods blindly.
Compare the best Project Zomboid server hostsProject Zomboid server FAQ
What is the difference between a Workshop ID and a Mod ID?
A Workshop ID tells Steam which item to download, so it belongs in WorkshopItems=. A Mod ID tells Project Zomboid which internal package to enable, so it belongs in Mods=. They are not interchangeable, and one Workshop item can contain several Mod IDs.
Why do my mods not load on Build 42?
The common causes are using a B41-only mod, copying only the Workshop ID and not the internal Mod IDs, or running mismatched game builds between server and clients. On B42, check for the expected common/ and 42/ structure and confirm the server log shows the mod being loaded rather than merely downloaded.
Do players need to subscribe to the mods themselves?
Usually no. The server advertises the required Workshop items and clients download what they need when they connect. What players do need is the same game build as the server, enough time for the downloads to complete, and a clean per-server cache if stale files are causing join errors.
Can I add mods to an existing world?
Yes, but back up first. Adding is usually safer than removing, and adding maps works best for unexplored areas because existing chunks are already saved. Removing item, tile or map mods from a live world is where you are most likely to create broken references.
How many mods can a server run?
There is no useful fixed number. The real limits are compatibility, Java heap and main-thread CPU time. A shorter, cleanly compatible mod list will usually outperform a huge list full of overlapping scripts and map packs.
More Project Zomboid server guides
The rest of our Project Zomboid server guides, plus the host comparison.
Written for Build 42 stable (42.21), with notes for legacy41 servers. Workshop IDs, Mod IDs and map names in the examples are made up: swap in the ones from your own mods.
