Project Zomboid server mods: Workshop IDs, load order and maps

Three lines in one file decide whether a Project Zomboid server has mods: WorkshopItems, Mods and Map in <servername>.ini. WorkshopItems is a list of numbers that tells the server what to download. Mods is a list of names that tells it what to load. Map is a list of map folders, in priority order, with the vanilla map last. They are three different lists and they do not accept each other's values, which is the single most common reason a mod is installed, downloaded, present on disk and doing absolutely nothing.

This guide covers where the files land, how to find the ID a mod actually wants, what load order does and does not fix, how map mods and spawn regions work, what Build 42 changed about mod folders, and the failures that follow a mod update. For the sandbox and server options themselves, see Project Zomboid server settings; for the admin account and the commands you will need when a mod misbehaves, see Project Zomboid admin commands.

How the server finds a mod at all#

A Project Zomboid dedicated server (Steam app 380870) reads mods from more than one place:

• Workshop downloads. Anything listed in WorkshopItems is fetched by the server itself at startup, into steamapps/workshop/content/108600/<workshopID>/. Note the app id: 108600 is the game, not the server, because workshop content belongs to the game.
• Local mods. Folders you upload yourself, into Zomboid/mods/<ModID>/. This is how you run a mod that was never on the workshop, or pin a version the author has since replaced.

The download step is the reason the installer asks for a Steam account. Project Zomboid's dedicated server, like Arma 3, DayZ and 7 Days to Die, cannot be installed or kept updated with an anonymous Steam login, and neither can workshop content. On RE:NODE the server is created immediately and the install waits on the Setup tab until you enter those credentials - which are stored as you typed them, so use a spare account that owns the game rather than your main one.

Everything in this guide happens in Zomboid/, the server's data directory - ~/Zomboid/ on Linux, %USERPROFILE%\Zomboid\ on Windows, and the folder the panel drops you into on a managed host. The config files are in Zomboid/Server/, the logs in Zomboid/Logs/, the saves in Zomboid/Saves/Multiplayer/<servername>/.

Workshop ID or mod ID: the difference that breaks installs#

A workshop item and a mod are not the same object.

The Workshop ID is the number in the item's URL, after ?id=. It identifies a download. One workshop item can contain several mods, and plenty do - map packs, mod collections published as a single item, mods that ship an optional add-on in the same upload.

The mod ID is a string declared inside the mod, in its mod.info file:

name=Better Firearmsposter=poster.pngid=BetterFirearmsdescription=Adds a set of civilian firearms.require=CommonLibrarymodversion=2.4.1

id= is what goes in Mods=. It is case sensitive and is frequently nothing like the display name on the workshop page. The reliable way to read it is to open the downloaded folder and look, rather than guess from the title: after the first start, list what is under steamapps/workshop/content/108600/ and read each mod.info. Many authors also print the mod ID on the workshop page, usually near the bottom, and that is worth trusting only because you can check it against the file.

require= lists other mod IDs the mod needs. The server does not resolve those for you: if a mod requires a common library, the library needs its own workshop ID in WorkshopItems and its own mod ID earlier in Mods.

The three lines that matter in servertest.ini#

The server's main config file is named after the server, so the default install gives you Zomboid/Server/servertest.ini along with servertest_SandboxVars.lua and servertest_spawnregions.lua. The mod lines look like this:

WorkshopItems=2392709985;2169435993;2875848298Mods=CommonLibrary;BetterFirearms;RavenCreekMap=Raven Creek;Muldraugh, KY

Semicolons separate entries in all three, with no spaces after them. The semicolon matters more than it looks: map names contain commas (Muldraugh, KY is one map), so a comma-separated list would be ambiguous and the game does not accept one.

A few other keys in the same file interact with mods:

Turn CheckModsNeedUpdate on. It costs nothing and it is the only warning you get before a silently updated mod breaks the next restart. Note that the ini's capitalisation is not consistent across every key in the file - copy the key out of the file the server generated rather than out of a guide, including this one.

Edit the file with the server stopped. Project Zomboid rewrites its ini on a clean shutdown, so a change made to a running server is usually overwritten the moment you restart it properly. SFTP and the file manager covers the edit-in-place workflow; the panel's file editor does the same job with syntax highlighting.

Load order and conflicts#

Mods load in the order they appear in Mods=, left to right. When two mods change the same file, the one loaded later wins. That gives you a workable ordering rule:

1. Libraries and frameworks first - anything other mods declare in require=.
2. Content mods next: guns, vehicles, items, professions.
3. Tweaks and overrides last, because their whole purpose is to beat something already loaded.
4. Map mods anywhere in the list. Their position in Mods= barely matters; what matters is Map=, which is a separate ordering and covered below.

The honest limit of this rule: load order only settles conflicts between mods that patch politely. A Lua mod that replaces a whole vanilla function wins regardless of where it sits, and two mods that both replace the same function will always break each other - the later one simply hides the damage until someone uses the feature the earlier one changed. If two mods are known to conflict, no ordering fixes it and the answer is to drop one.

Balance mods that touch the same sandbox values behave the same way, and the symptom is subtle: your loot rarity looks wrong even though you never changed it, because a mod rewrote the value at load. When numbers do not match what the settings file says, suspect a mod before you suspect the setting.

Map mods, the Map line and spawn regions#

Map mods are the part people get half-right. A map mod is usually two things at once: a regular mod (so it needs its ID in Mods=) and a map (so it needs its folder name in Map=). Install only one of the two and you get one of two classic symptoms - the map never appears, or the map appears with its buildings missing their custom furniture.

The value in Map= is the folder name under the mod's media/maps/, and the vanilla entry must be last:

Map=Raven Creek;Grapeseed;Muldraugh, KY

Priority runs left to right. The first entry wins for any cell it occupies. Because every map mod is placed at fixed cell coordinates on the same grid as the base map, two mods that were built for the same empty corner of the world will overlap, and the one listed second loses the overlapping cells - which usually means half a town is missing rather than a clean failure. There is no tool that checks this for you. Read each map's workshop page for its cell coordinates, and if two collide, one of them has to go.

Two further details:

• Tile packs. Most custom maps depend on a shared tileset mod, listed as a required item on their workshop page. Without it you get invisible walls, missing furniture or blocks of magenta. Add the tile pack's workshop ID and mod ID like any other dependency.
• Spawn points. A map being loaded does not make it a place players can start. Spawn regions are declared in <servername>_spawnregions.lua:

function SpawnRegions()    return {        { name = "Muldraugh, KY", file = "media/maps/Muldraugh, KY/spawnpoints.lua" },        { name = "Riverside, KY", file = "media/maps/Riverside, KY/spawnpoints.lua" },        { name = "Raven Creek", file = "media/maps/Raven Creek/spawnpoints.lua" },    }end

The file path is relative to the game's media folders, and the map mod has to actually contain a spawnpoints.lua - not all do, and one that does not can only ever be walked to. If your custom map does not appear in the character creation list, this file is why, nine times out of ten.

What Build 42 changed#

Build 42 reached the stable branch in July 2026 and brought multiplayer with it, so most new servers are now on 42 rather than 41. For mod administration, the change that matters is the folder layout.

• Build 41 puts mod.info, poster.png and media/ at the root of the mod folder.
• Build 42 uses version subfolders. A mod ships a 42/ folder holding mod.info and media/, alongside a common/ folder for content shared between builds. The game loads common/ plus the closest supported version folder.

The practical consequence is that a Build 41 mod dropped into a Build 42 server is not seen at all. It does not error, it does not warn in a way you will notice, it simply never appears in the loaded list. If a mod you are sure you installed is missing from the console output at startup, open its folder and check whether there is a 42/ in it.

Because the two builds want different layouts, a well-maintained mod supports both and a stale one does not. Check the workshop page for a stated build before adding anything, and expect the point releases after a stable launch to keep breaking things for a while - a mod that works on one 42.x patch can fail on the next. What to do when a mod update breaks is the general version of this problem.

Clients, sync and mod mismatch#

Project Zomboid handles client distribution better than most games. When a Steam client connects to a server with WorkshopItems set, it subscribes to and downloads those items before joining. You do not have to hand out a mod list or a zip.

What it does not do is tolerate a mismatch. If a player has a different version of a mod than the server, or has extra mods loaded that change the same content, they are dropped at connection or desync shortly after. Two situations cause this repeatedly:

• The player subscribed manually and Steam has a stale copy. The fix is to unsubscribe, verify, and let the server's list pull it again.
• The server updated a mod and the player has not restarted Steam. Steam updates workshop content lazily. A full restart of the client, not just the game, is the reliable fix.

Client-only mods - interface tweaks, sorting, minimaps that do not add content - are fine and do not need to be on the server. Anything that adds items, changes recipes or touches the map has to be on both, at the same version.

Updates, removals and the wipe you did not plan#

Removing a mod from a live server deletes its content from the save. Items from that mod disappear from every container and every player inventory the next time those chunks load. Vehicles from a vehicle mod vanish with whatever was in them. This is expected behaviour rather than corruption, but it is not reversible without a backup, and the only sane way to try a mod is to try it somewhere you do not mind losing.

A practical routine:

1. Stop the server cleanly. A clean stop writes the ini and flushes the save.
2. Take a backup and keep it off the server. BackupsOnStart gives you a local copy, which protects you from a bad mod but not from a lost machine - see backups that actually restore.
3. Change one thing. One mod added, or one removed, per restart.
4. Start, and read the console. The loaded mod list and any Lua errors print in the first thirty seconds.
5. Join once yourself before telling anyone the server is back.

On RE:NODE, steps 2 and 5 are the ones the panel helps with: backup slots are on every Project Zomboid plan and restore with a button, the console shows unfiltered output with the Lua stack traces intact, and the Schedules tab can take a backup before a nightly restart so there is always a recent copy from before the last mod change. Backups are stored off the machine they protect, which is the half that matters when the problem is not the mod.

Mods also cost memory. The base server is comfortable in 3 GB for a small group; a list of twenty content mods, a custom map and a vehicle pack is a 6-8 GB server, and the growth is mostly in the Java heap rather than in the save. If the container hits its memory limit it is stopped and restarted clean rather than left to swap, so a mod list that outgrows the plan shows up as repeated restarts rather than as slow play. Keeping a modded server clean has the general hygiene rules; Steam Workshop mods on dedicated servers covers how the download side works across games.

Troubleshooting#

The mod downloaded but is not loaded. The mod ID in Mods= is wrong, or the workshop item contains a different ID than you assumed. Read mod.info in the downloaded folder.

The server starts, then exits with a Lua error. A mod is incompatible with the build or with another mod. The last mod name printed before the stack trace is usually, though not always, the culprit. Remove mods in halves rather than one at a time.

The map mod loads but nobody can spawn there. Missing entry in <servername>_spawnregions.lua, or the map has no spawnpoints.lua.

Half a modded town is missing. Two map mods claim the same cells. The one later in Map= lost. Check the coordinates on both workshop pages.

Players are kicked with a mod mismatch. Version skew. Have them restart Steam entirely; if that fails, unsubscribe and resubscribe the mod named in the message.

Everything worked yesterday. A workshop item updated overnight. With CheckModsNeedUpdate=true the console will have said so. This is the argument for keeping a copy of every mod folder that works, so you can put a version back by hand.

The server hangs for minutes at startup. Normal with a long mod list and a custom map the first time, because the map needs indexing. If it happens on every start, one of the mods is doing work at load that it should not.

FAQ#

Where do I find a mod's ID rather than its Workshop ID?

In mod.info inside the mod folder, on the id= line. After the server has downloaded the item once, the folder is under steamapps/workshop/content/108600/<workshopID>/. The workshop page often prints it too, but the file is the authority.

Do players need to install the mods themselves?

No. A Steam client joining a server with WorkshopItems set downloads and enables those items automatically. They only act manually when Steam has cached a stale version, which a full Steam restart usually clears.

Can I add a map mod to a world people are already playing?

Yes, adding is safe - the new cells are empty until someone walks into them. Removing a map mod from a live save is not safe, and changing which maps overlap is effectively a wipe of the overlapping area.

How many mods can a Project Zomboid server run?

There is no hard limit, and people run fifty. The practical limits are memory and startup time. Budget roughly 3 GB for vanilla plus a group, and 6-8 GB once you have twenty content mods and a custom map.

Why did my items disappear after a restart?

A mod was removed or failed to load, and the save dropped everything belonging to it. Restore a backup taken before the change, put the mod back at the same version, and only then decide whether you still want it gone.

Does load order matter for map mods?

In Mods= it barely does. In Map= it decides everything: the first entry wins any cell two maps both claim, and Muldraugh, KY goes last so the vanilla world fills in whatever the mods did not place.