Workshop item ID vs Mod ID: the distinction everything hinges on
A Steam Workshop item and a Project Zomboid mod are two different things, and a server deals with both:
- Workshop item ID: the number in the Workshop page URL (
?id=...). It identifies the Steam Workshop package whose content the server needs available. - Mod ID: the identifier for Project Zomboid mod content inside that package that the game loads, usually the internal folder name of the mod content in the Workshop download.
WorkshopItems tells the server which Workshop packages to make available. Mods tells it which mod content inside those packages to load. One Workshop item may contain one or more Mod IDs, so the mapping is not guaranteed to be one-to-one. What matters is that every configured Mod ID comes from Workshop content that is actually available to the server, and that the Mod IDs you configure are the ones documented by the mod author or package: those instructions are authoritative.
Adding one mod, step by step
Take the QP Server Welcome & Rules mod as an example. Its Workshop page shows the item ID in the URL, and its QUESTPAUSE page lists both values:
WorkshopItems=3756235810 Mods=QPWelcomeRules
Add the WorkshopItems entry, add the Mod ID its documentation lists, save servertest.ini, and restart the server. When the server comes up, the log lines the mod itself writes (or its visible effects in game) tell you it loaded. That is the whole loop; multi-mod servers just repeat it with discipline.
Adding several mods at once
Both lines accept multiple entries, separated by semicolons. A three-mod setup using QUESTPAUSE mods looks like this:
WorkshopItems=3756235810;3759611973;3762513228 Mods=QPWelcomeRules;QPVehiclePowerReminder;QPContainerActivityLog
For a package that exposes several Mod IDs, the item ID appears once on the WorkshopItems line while every documented Mod ID goes on the Mods line. The two lists are therefore not guaranteed to have the same number of entries, and unequal counts are not automatically an error: what matters is that every configured Mod ID comes from Workshop content the server actually has available. The Mods= value for each mod always comes from its documentation: for the QP catalog, every mod page shows its install block.
If a mod author documents several Mod IDs for one Workshop item, add all of them to the Mods line. The one-item-one-ID assumption is the most common surprise with larger packs, so read the install notes a mod ships with before adding it.
Do not assume load order is irrelevant. Dependencies, overrides, maps, and compatibility can all make order matter, and mod packaging and load-order capabilities differ across Build 41 and Build 42, with Build 42 adding explicit load-order functionality plus dependency and incompatibility information. Preserve the order each mod author recommends, document the order you run, and avoid changing it casually on an established server.
A formatting workflow that scales
Hand-maintaining two parallel lists across a growing mod set is how typos get in. The workflow our admins use, which is also the tool we ship:
- 01Collect each Workshop package's item ID and the Mod IDs its documentation lists, side by side, from the mod's page or Workshop description.
- 02Paste what you collected into the Mod List Formatter. Newlines, semicolons, or an existing ini line all work as input.
- 03Copy the generated WorkshopItems and Mods lines into servertest.ini as a pair.
- 04Restart the server and check the log for the first mod it fails to resolve, if any.
The formatter also warns when it spots obviously malformed input: numeric IDs in the Mods line, or folder names in WorkshopItems.
Updating a modded server without breaking it
Mods update on the Workshop side whether you touch anything or not, so the update routine matters more than the initial install:
- Announce mod updates to players before the restart, not during it. A restart warning with a reason keeps the Discord calm.
- Back up the server profile before a mod update batch, the same as a settings change. Persistent worlds deserve the caution.
- Update in batches and restart between batches when you can. When something breaks, a small batch tells you which mod it was.
- After an update, verify the Mods line still matches what the documentation for each mod specifies: a mod that renamed its Mod ID between versions will drop out of the Mods line silently.
The backup mindset for persistent worlds
Every change to a persistent server carries two risks: the config you are editing and the world it affects. Before touching mods or settings on a long-term world:
- Back up the profile folder (configs) and the world save folder before batch changes or big mod updates.
- Test risky changes on a private server or a second instance first when possible, not on the live world at peak hours.
- Keep a copy of the last known-good servertest.ini. Rolling back a config takes a minute; reconstructing it from memory does not.
Common mistakes when adding mods
- Putting the Workshop item ID in the Mods line, or the mod folder name in WorkshopItems. The two lines want different values.
- Adding only some of the Mod IDs a multi-ID pack documents, so a configured Mod ID points at content the server does not have available.
- Editing servertest.ini and forgetting the restart, then concluding the mod is broken.
- Adding a mod the client also needs without telling players, then fielding join failures.
If the server is already failing to start or mods are missing after a change, the mods not loading fix list walks through it symptom by symptom.
Where this fits in running a server
Mods are one layer of a modded server; the settings around them shape how the world plays. The servertest.ini settings guide covers the other half, and the QUESTPAUSE Project Zomboid hub ties together our worlds, tools, and the full mods catalog. Mod support, bug reports, and multiplayer testing all happen on the community Discord.