Before anything else
Two habits prevent most of this page:
- Back up the server profile before editing configs on a persistent world. Every fix below is cheaper with a copy of the last known-good servertest.ini.
- Read the server log. The Project Zomboid log names the first item it fails to resolve, which usually is the whole answer.
Symptoms and fixes
Server starts, but the mod never loads
Likely causes
- A configured Mod ID is not provided by Workshop content available to the server: the Mods line names content the server never downloaded.
- The wrong Mod ID was copied, or required Mod IDs documented by the package were omitted.
Fix
Verify each configured Mod ID is documented by installed Workshop content, and that Workshop item IDs and Mod IDs are in their correct respective fields. Follow author-specified dependencies and order where the documentation applies them. Use the Mod List Formatter to normalize both lines and catch obviously malformed values, then read the first unresolved item in the server log.
Server log shows a workshop item it cannot resolve
Likely causes
- The WorkshopItems entry contains a mod folder name or a typo instead of the numeric Workshop item ID.
- The ID was copied from the wrong item (a collection or a different mod).
Fix
Re-copy the numeric ID straight from the mod's Workshop page URL (?id=...) and fix the entry. Each mod page in the QP catalog also lists its exact Workshop ID.
Files download, but the mod is not available to load
Likely causes
- The Mods line uses a guessed name instead of the mod's actual folder ID.
- A multi-ID pack added only partially, so one of its internal mod IDs is missing.
Fix
Take the Mod IDs from the documentation of the mod, never from the Workshop title. Where a package exposes several internal Mod IDs, enable the ones its installation instructions require for the setup you are running: a package can include optional modules or variants that are not all meant to be enabled at once.
Startup fails with a configuration error
Likely causes
- Missing or extra semicolons, stray spaces, or line-wrapping artifacts from copy-paste.
- Numeric Workshop IDs pasted into the Mods line, or folder names pasted into WorkshopItems.
Fix
Regenerate both lines cleanly with the Mod List Formatter instead of patching by hand: paste whatever you have, copy the result back, restart.
Odd behavior, doubled log lines, or a refusal to start
Likely causes
- The same mod listed twice, often once from an old entry and once from a fresh paste.
- Two versions of the same mod enabled together.
Fix
Remove duplicates so each Workshop item and each Mod ID appears once. Some mods explicitly forbid running multiple versions at once (the QP reputation mod documents exactly this), so deduplicate before anything else.
Mod missing after a Build 41 to Build 42 change (or the reverse)
Likely causes
- The mod only ships one build and your server runs the other.
- An older listing of the mod predates Build 42 support.
Fix
Check the mod's stated build support before adding it. Every QUESTPAUSE mod ships Build 41 and Build 42 in one Workshop item with one Mod ID, so the same two config lines cover both builds; for other mods, the Workshop page documents what it supports.
Players cannot join after a mod change, or the mod works for some players and not others
Likely causes
- The mod is server-side only but was announced as a required client install (or the opposite).
- A client-side mod version differs from what the server expects.
Fix
Read the mod's own install notes on who needs it, then match the server and client mod sets. Where a mod must match exactly, update clients and server together as part of the same maintenance window.
Mod updated on Workshop, but the server still runs the old behavior
Likely causes
- The server's local Workshop cache has not refreshed to the new version yet.
- The update landed mid-session and the server has not restarted since.
Fix
Restart the server after a Workshop update and give the platform a moment to sync; if behavior still looks old, re-check the mod page for update notes before touching your config. Config-side fixes cannot pull a download the server does not have.
Nothing changed in game after editing servertest.ini
Likely causes
- Most servertest.ini changes only apply on server start.
- The edit landed in a profile folder the running instance does not read.
Fix
Restart the server, and if the change still does nothing, confirm which profile folder your instance actually uses (hosting panels and multiple instances each keep their own servertest.ini).
Verify after any config change
- 01Restart the server (most config changes apply on start, not live).
- 02Watch startup: the log names the first mod or workshop item it fails to resolve, if any.
- 03Join once and confirm the mod's actual behavior in game, not just the log lines.
- 04If it loads now, keep a copy of the working servertest.ini as your new last known good.
Prevent it next time
Almost every symptom above comes from the same root: hand-maintained lines where a copied ID is wrong, undocumented, or malformed. The how to add mods guide shows the workflow that prevents that from the start: collect each Workshop item ID and the Mod IDs its documentation requires, keep the lines readable, and restart and verify after every change, and the QUESTPAUSE Project Zomboid hub links our worlds, tools, and mods. For a concrete worked example of documented install blocks, QP Container Activity Log shows exactly what a clean install section looks like.
Still stuck after walking the list? Bring the log to the community Discord: the admins there debug this exact pipeline every week.