PZ Mods Installed but Not Loading - Diagnosis

"My PZ mods are installed but not actually loading"

The Workshop tab says Installed, you can see the .zip in the Workshop content folder, the server starts without errors, but when you join the game the mod is not there. Or your players cannot join because of a "client has mod that server does not" mismatch. This article is the troubleshooting decision tree for the five real causes of this symptom.

Work through the list in order. The first three causes account for the overwhelming majority of cases on Supercraft servers.

Cause 1: Mods= and WorkshopItems= are out of sync

Project Zomboid uses two separate config lines per mod:

Mods=Tsarslib;TrueActionsDancing;FluffyHair
WorkshopItems=2447729538;2169435993;2447729538

• WorkshopItems takes the numeric Workshop ID. This is what SteamCMD uses to download the zip.
• Mods takes the internal mod ID (read from the mod's own mod.info file). This is what the game uses to load.

If you have the Workshop ID but not the Mod ID, the file downloads and never loads. If you have the Mod ID but not the Workshop ID, SteamCMD never fetches the file. Both must be present and both must be correct.

Fix: Open servertest.ini in the File Manager. Check both lines. If you used the panel's Mods tab to add the mod, both should be there automatically; if you edited manually, double-check the Workshop page for the mod's listed Mod ID (it usually has both shown near the bottom of the description).

The panel's Add mod button writes both lines correctly. If you suspect manual edits got out of sync, click the button again - it merges the missing entry without duplicating existing ones.

Cause 2: Mod ID typo (case matters on Linux)

Mod IDs are case-sensitive on the Supercraft Linux nodes. Tsarslib, tsarslib, and TSARSLIB are three different mods as far as the game is concerned. The Workshop page may show the ID in a different case from what the mod.info file uses; the file is the authoritative source.

Fix: Open the actual mod.info file inside the Workshop content directory:

# B41 (stable):
~/prz/bin/steamapps/workshop/content/108600/<workshop_id>/mods/<mod_id>/mod.info

# B42 (unstable): the file path inside the workshop tree is the same; what changes is where the parsed metadata lives

The id= line in mod.info is what your Mods= entry has to match. Verbatim, case-sensitive.

Cause 3: Missing dependency mod

Many PZ mods depend on a library mod (Tsarslib, MoreBuilds, ModUtility). If the dependency is not in your Mods= list before the dependent mod, the dependent mod silently fails to load.

Fix: Open the Workshop page for each mod and read the description. Any line that starts with "Requires:" or "Dependency:" is a mod you also need to install. Add the dependency:

• To WorkshopItems (numeric ID)
• To Mods (Mod ID, placed before the dependent mod in the list)

The order in Mods= matters. Libraries go first, then mods that use them. A general-purpose rule: map mods first, library mods second, gameplay mods last.

Cause 4: Mod is published for the other branch

A mod can target Build 41, Build 42, or both. A B42-only mod will not load on a B41 server, and vice versa. Most Workshop pages declare which branch is supported in their description. If a mod was published a year ago and not updated, it is probably B41-only.

Fix: Check the Workshop page. If it says "Build 41 only" and your server is on B42 unstable, the mod will not work until the author updates it. If the page does not say, look at the mod's own mod.info for a require= line referencing a game version.

Switching your server branch to match the mod is one option. The other is finding an alternative mod that supports your branch. There is no compatibility shim - the build differences in B42 are too large.

Cause 5: Joining players have not subscribed to the same mods

If the server loads the mod successfully but a player gets "client has mod that server does not have," the mismatch is on the player's end. Project Zomboid does not auto-download mods to clients the way some games do; each player has to subscribe to the same Workshop items on Steam before joining.

Fix: Make a Steam Workshop collection with every mod your server uses, then share the collection URL with your players. They subscribe to the collection (one click), the mods download, and the version check on join passes.

Tell players to start the game once after subscribing, so the client downloads and indexes the mods locally before trying to connect.

How to read the server log

The PZ server writes a debug log per session. To see whether a mod loaded:

# B41:
~/prz/bin/Zomboid/Logs/<date>_DebugLog-server.txt

# B42:
~/Zomboid/Logs/<date>_DebugLog-server.txt

Grep for these patterns:

• Loading mod: <ModID> - the mod loaded successfully
• Mod not found: <ModID> - the Mods= entry could not be matched against any installed mod (cause 1, 2, or 3)
• Mod has wrong target version - branch mismatch (cause 4)
• java.lang.NullPointerException from a mod class - the mod loaded but is buggy or incompatible with your other mods

The Logs tab in the panel shows the same content. You do not need shell access to read it.

A 60-second sanity check

Before you debug deeper, run this short routine after every mod change:

1. Save the config and restart the server.
2. Wait for the panel's status to flip to Running.
3. Open the Logs tab and grep for Loading mod: - you should see one line per mod in your list.
4. Connect with your own client and check the in-game Mods menu - every mod you expect should be ticked.

If a mod is missing from step 3 or step 4, return to cause 1 at the top of this page and walk down.

What about the panel's Workshop tab marking it Installed?

"Installed" in the panel means SteamCMD reported a successful download. It does not mean the server actually loaded the mod. The Workshop tab cannot tell whether you remembered to add the Mod ID to the Mods= line - that is between you and the config file. The label is accurate; it is just answering a different question than "is the mod active in the world."

Still stuck?

If you walked through all five causes and the mod still does not load:

• Copy the relevant lines from servertest.ini (Mods=, WorkshopItems=, Map=) into a support ticket.
• Include the Workshop URL of the problematic mod.
• Open DebugLog-server.txt and copy the section from the last server start until the first non-mod log line.
• Mention which branch (B41 stable or B42 unstable) you are on.

With those four pieces of information, support can identify the cause without further back-and-forth.

Related guides

• How to install mods on a PZ server
• PZ Build 42 file paths reference
• Mod Manager basics
• Workshop item version is different

Want a PZ host where the Mods tab writes both lines for you and verifies load success in the log? See plans. Add a mod, click Save and Restart, the panel confirms it loaded.