Check whether the failure happens while downloading an item, selecting its component or joining the world. Those are separate operations. A Workshop entry marked installed does not prove the server loaded the intended mod, and a visible mod in the client does not prove multiplayer compatibility.
This guide covers Steam PC dedicated servers, primarily current Build 42. The example paths match our Linux setup: /srv/pz/server, /srv/pz/Zomboid, account pz, name servertest. For an existing Build 41 group, use its corresponding mod releases and the separate branch guide. Do not transplant a Build 41 mod list into a live Build 42 world.
Separate the download identifier from the component identifier#
A Workshop item has a numeric ID in its Steam page URL. That item can contain one component, several alternatives or dependencies. A component has its own identifier in the mod's metadata. The displayed Workshop title is not necessarily that identifier.
WorkshopItems selects downloads. Mods selects components to load. Keep a small inventory with the item URL, intended component, required dependencies, supported game release and multiplayer notes. Read each author's installation instructions and recent release notes before assuming that a [B42] title applies to the exact server patch.
Inspect the current server selection without printing passwords:
sudo -iu pz sed -n '/^WorkshopItems=/p; /^Mods=/p; /^Map=/p' /srv/pz/Zomboid/Server/servertest.ini
sudo -iu pz find /srv/pz/Zomboid/Logs -maxdepth 2 -type f -printf '%TY-%Tm-%Td %TH:%TM %p\n'
Check that this is the file selected by the running -servername and HOME. Editing a configuration under your own SSH account will not change a process running as pz.
Understand why Build 42 has nested mod files#
The developer's mod architecture explanation describes versioned component directories and a shared common directory. Build 41's files can remain at the component root while newer builds use a compatible versioned subdirectory. A top-level search for mod.info can therefore miss the metadata that the current game uses.
Inspect the Workshop location reported by the current server log. A typical installation keeps downloaded game items under steamapps/workshop/content/108600, but do not assume that your wrapper or container uses the same parent directory. Search inside the one item being investigated and read its relevant metadata. Linux paths are case sensitive.
Do not move 42 or common contents into the root as a general repair. That creates a local fork, can break another supported build and may be overwritten by the next Workshop update. An incompatible Lua API also cannot be repaired by moving directories. The developer's 42.13 migration resources document a real API transition; the mod author must support the API your server runs.
Generate a small server configuration with the matching client#
In a client on the same full version as the server, open Host → Manage Settings and create a separate test configuration. Add one current multiplayer-compatible mod and all its required dependencies through the server's Workshop and mod selection screens. Main-menu mod activation alone does not configure the hosted server.
Inspect the generated test .ini, including both selection lines. Preserve the syntax, prefixes and separators produced by this build. Early Build 42 forum threads contain conflicting suggestions about backslashes and checksum settings; copying one old line into every release is unreliable. The dedicated-server discussion illustrates that disagreement rather than establishing a universal fix.
With the server stopped, transfer only the intended test settings to a disposable server profile. Keep its password private and confirm the destination ownership. Do not overwrite the production profile or account database. Start the trial using the packaged launcher and the new server name. If it would reuse the original ports, stop the original process first.
Use the first relevant log failure to choose the next action#
| Observation | Next check |
|---|---|
| Workshop download never reaches a usable state | Item availability, server Steam connectivity, free disk space and write permissions |
| Item is installed but a required component is missing | Generated component selection, versioned metadata and dependencies |
| Server starts but the client reports differing files | Exact game build, selected item releases, duplicate local copies and dependency versions |
| Vanilla joins work, a small mod test fails | First mod-specific error and author's multiplayer compatibility notes |
| Only the old world fails | World dependency history and a separate intact restore test |
Refresh the specific failed item only after preserving the current state and reading its download error. Removing the whole Workshop cache makes every item a new variable. Never disable Lua checksum validation merely to silence a mismatch: investigate why the two sides loaded different content.
Protect the original world during testing#
Before changing an established modded server, complete a graceful save and quit, wait for exit and retain an off-machine backup of configuration, world, account databases and the matching installation. Keep an inventory of the exact downloaded mod versions where possible; a future Workshop download can change even when the item ID stays the same.
Test on a new world first. Add dependencies and dependent mods together, then enlarge the selected set in recorded groups. Removing a dependency while keeping its consumer does not create a useful isolation test. Map mods need their own placement and existing-world instructions from the author; do not assume already explored areas will regenerate.
After a successful trial, apply the verified selection during a planned stop. Join with a normal matching client, check the feature the mod actually changes, save, restart and reconnect. If it fails, stop again and restore the original complete compatible set. Keep the failed trial for diagnosis rather than merging its world or player databases into the backup.
