Mods are a big part of why Project Zomboid servers stay fun for months. Extra vehicles, new maps, better loot, quality of life tweaks: the Steam Workshop has thousands of them. Getting them onto a dedicated server is not hard, but the game is strict about how you list them, and one wrong ID is enough to stop the server from starting or kick every player on join. This guide walks through the whole process, from finding the right IDs to fixing the errors you are most likely to hit.
How Project Zomboid loads mods on a server
A dedicated server reads its settings from a file named after the server. The default name is servertest, so the files you care about are:
Zomboid/Server/servertest.ini- the main server settings, including the mod list.Zomboid/Server/servertest_SandboxVars.lua- sandbox settings such as zombie population, loot rarity and mod options.Zomboid/Server/servertest_spawnregions.lua- where players can spawn, which matters for map mods.
If your server uses a different name, the files use that name instead (for example myserver.ini). Three lines in the .ini file control mods:
| Line | What it holds | Example |
|---|---|---|
WorkshopItems= | Steam Workshop IDs to download | 2169435993;2392709985 |
Mods= | Mod IDs to enable, in load order | modoptions;tsarslib |
Map= | Map folders to load, custom maps first | Bedford Falls;Muldraugh, KY |
All three use a semicolon between entries, with no spaces around it. The server downloads everything in WorkshopItems= when it starts, then enables only the mods named in Mods=. Downloading a Workshop item does not switch anything on by itself.
Workshop ID vs Mod ID
This is where most people go wrong. Every mod has two different identifiers, and they go on different lines.
Workshop ID
The Workshop ID is the number at the end of the Steam Workshop page URL. For a page at steamcommunity.com/sharedfiles/filedetails/?id=2169435993, the Workshop ID is 2169435993. It always contains only digits, and it goes in WorkshopItems=.
Mod ID
The Mod ID is the internal name the game uses. Most authors list it near the bottom of the Workshop description as Mod ID: something. If they don't, subscribe to the mod in Steam and look in its folder:
steamapps/workshop/content/108600/<Workshop ID>/mods/<mod folder>/mod.infoOpen mod.info and find the id= line. That value is the Mod ID, and it goes in Mods=. Mod IDs are case sensitive, so copy them exactly.
One Workshop item, several mods
A single Workshop item can contain more than one mod. A vehicle pack might ship a main mod, an optional extra and a compatibility patch, each in its own folder under mods/. You list the Workshop ID once, then add only the Mod IDs you actually want. Enabling two variants of the same mod that are meant to be alternatives is a common cause of strange bugs, so read the description to see which ones the author recommends.
Adding mods step by step
- Stop the server. The server writes its settings back to the
.inifile when it shuts down. If you edit the file while it is running, your changes can be overwritten. - Collect the IDs. For each mod, note the Workshop ID and every Mod ID you want from it. Also check the description for required mods (libraries and frameworks), and add those too.
- Open
servertest.iniin your control panel's file manager or over SFTP. - Edit the three lines. Add Workshop IDs to
WorkshopItems=, Mod IDs toMods=and, for map mods, the map folder toMap=. - Save and start the server. Watch the console. The first start after adding mods takes longer because the server downloads them.
- Join and test. Players are prompted to download missing mods when they connect, so they do not need to install anything by hand.
A finished set of lines might look like this:
WorkshopItems=2169435993;2392709985;2337452747
Mods=modoptions;tsarslib;Bedford Falls
Map=Bedford Falls;Muldraugh, KYThe lists don't need to match one to one. One Workshop ID can provide several Mod IDs, and a Workshop item that only contains a library may provide one Mod ID that several other mods depend on.
Load order
The order in Mods= is the order the game loads mods in. When two mods change the same file, the one loaded later usually wins. A safe pattern is:
- Frameworks and libraries such as mod options or shared vehicle libraries.
- Tile packs that maps depend on.
- Content mods such as items, vehicles, weapons and professions.
- Map mods.
- Patches and compatibility fixes, after the mods they patch.
- Tweaks that adjust other mods, last.
If a mod's description says it must load after another one, follow that. Each mod.info can also include a require= line naming the Mod IDs it depends on. If one of those is missing from your list, the mod may fail to load or throw errors as soon as a player joins.
Map mods and the Map= line
Map mods need one more step. Besides the Workshop ID and Mod ID, you have to add the map's folder name to Map=. You will find it in the mod's files at:
mods/<mod folder>/media/maps/<map folder name>The map folder name is often different from the Mod ID, so check it instead of guessing. Custom maps go before the base map, and Muldraugh, KY should always stay at the end of the line, including the comma and space:
Map=Raven Creek;Bedford Falls;Muldraugh, KYA few more things to watch with maps:
- Tile packs: many maps need a separate tile pack mod. Without it, buildings show up as missing textures or empty floor.
- Overlapping maps: two maps that cover the same cells will clash. The descriptions usually say which cells a map uses and what it conflicts with.
- Spawn points: if you want players to start in a new town, add its spawn region to
servertest_spawnregions.lua. Map authors usually include the lines you need. - Existing saves: adding a map to a running world mostly works for cells nobody has visited yet. Areas that were already generated keep their old layout. Removing a map from an existing world can break saves, so take a backup first.
Fixing version mismatch errors
The error you will see most often is a mismatch between the server's copy of a mod and the player's copy. It usually appears as a kick on join with a message saying a Workshop item is different from the server's version, or that a mod's version doesn't match.
Why it happens
The server downloads Workshop updates only when it starts. When an author pushes an update, Steam updates players straight away, but the server keeps the old copy until it restarts. From then on, every player with the new version is turned away.
How to fix it
- Restart the server. This is the fix in almost every case. The server downloads the updated mod on startup.
- Check from the console. The admin command
checkModsNeedUpdateasks Steam whether any of the server's mods are out of date and reports the result in the console. - Schedule restarts. A regular restart, for example every 6 or 12 hours, keeps mods current without anyone having to notice the problem. Warn players with
servermsgfirst. - Use an update checker mod. Some community mods watch for Workshop updates and restart the server with a countdown when one is found.
- Player side: if one player still gets the error after a restart, Steam may not have finished updating their copy. Restarting Steam, or unsubscribing and resubscribing to the mod, usually clears it.
If the server itself fails to start after you add mods, read the console from the top. Look for a Workshop ID that failed to download (often a typo, or an item that was removed or made private), or a Mod ID that the server could not find. A Mod ID that is spelled with the wrong case counts as missing.
Sandbox settings for mods
Many mods add their own options, such as spawn rates for new vehicles or the strength of a new mechanic. After the first start with a new mod, the server adds those options to servertest_SandboxVars.lua. To change them:
- Stop the server.
- Open
servertest_SandboxVars.luaand find the section named after the mod. - Change the values, keeping the Lua syntax intact (commas at the end of each line matter).
- Start the server again.
Sandbox settings are stored in the world save too, so some changes only fully apply to a new world. Keep a copy of the file before editing it: a single missing comma can stop the server from reading the whole file.
Useful admin commands
These commands work in the server console without a slash, or in the in-game chat with a slash in front, as long as you have admin access:
| Command | What it does |
|---|---|
setaccesslevel "name" admin | Gives a player admin rights |
checkModsNeedUpdate | Checks whether any Workshop mods have updates |
servermsg "text" | Broadcasts a message to everyone, handy before a restart |
save | Saves the world |
quit | Saves and stops the server |
reloadoptions | Reloads some settings from the .ini without a restart |
players | Lists connected players |
Note that reloadoptions does not load new mods. Any change to WorkshopItems=, Mods= or Map= needs a full restart.
Good habits for a modded server
- Add mods a few at a time. If the server breaks after adding three mods, you know where to look. After adding thirty, you don't.
- Back up before big changes. Copy the world save and the server files before adding or removing maps or large overhaul mods.
- Don't remove mods from a live world lightly. Items, vehicles and buildings from a removed mod can leave errors or broken objects behind.
- Check the game build. Build 41 and Build 42 mods are not always compatible. Make sure every mod supports the build your server runs.
- Keep a list. A simple note of each mod, its Workshop ID, Mod ID and why you added it makes troubleshooting much faster later.
Running it on Zettako
On a Zettako Project Zomboid server you edit servertest.ini and the sandbox file from the control panel, watch the console as mods download, and restart when an update comes out. Premium plans run on faster processors with DDR5 memory, which helps on heavily modded servers with large maps. If a mod won't load, open a ticket and our team will help you track it down.