Project Zomboid WorkshopItems and Mods Mismatch

Protect the modded world before changing lists

1. 1Run console save and quit, then wait for process exit.
2. 2Copy the Server configuration family, Multiplayer save, owner database, backups, logs, and current mod/Workshop content record.
3. 3Keep the first failing log and exact ordered WorkshopItems and Mods strings.
4. 4Work on a copied cache root with outside access disabled.

Understand the two namespaces

• WorkshopItems contains numeric IDs from Steam Workshop pages and tells Steam what to obtain.
• Mods contains internal IDs declared by the downloaded content and tells Project Zomboid what to load.
• One Workshop item can expose multiple internal mod IDs.
• Dependencies and load order can matter even when every individual ID is spelled correctly.

Build a verified mapping

1. 1Open each trusted current Workshop entry and record its numeric item ID, internal mod ID or IDs, dependencies, and Build 42 status.
2. 2Remove duplicate or stale entries from a test copy, not from the only production configuration.
3. 3Order dependencies before dependent mods where their publisher requires it.
4. 4Align server and client versions; a cached client copy does not prove the server received the same update.

Read the first real failure

Start privately and read the earliest missing-ID, dependency, or script error rather than the final generic disconnect. Correct one mapping or dependency group, restart, and keep each log. Adding and removing many mods at once makes a successful recovery impossible to attribute.

Do not save over missing mod content

If the world opens without structures, items, vehicles, maps, or rules owned by a required mod, stop immediately. Restore the copied pre-change snapshot and wait for a compatible mod build or a publisher-documented removal path. Reopen only after a private join, save, quit, and second load preserve the expected content.

Interpret download, load, and client errors separately

A Workshop download failure happens before the game can evaluate an internal mod ID; inspect Steam access, item availability, and the numeric WorkshopItems entry. A downloaded item followed by a missing-mod message points toward its internal ID, dependency, case, or Build 42 compatibility. A server that loads the mod but rejects a client points toward different cached versions or client-required dependencies.

Record the numeric item ID, every internal ID it provides, last update time, dependency chain, and the first server log error in a small manifest beside the backup. Re-run the same manifest after an update rather than rebuilding the list from memory. This also makes a disappeared or renamed Workshop item visible before the production world starts without its data-bearing content.

Branch on the earliest failing stage

If Steam never obtains an item, hold the Mods list constant and investigate the numeric WorkshopItems entry, item availability, Steam access, and the server's download log. If the item downloads but Project Zomboid says an internal mod is missing, inspect that item's current declared IDs, case, dependencies, and Build 42 support. Do not substitute the Workshop number into Mods; it represents a different namespace.

If every requested internal ID loads but scripts or assets fail, isolate the first dependency or compatibility error on the copied cache. If the server reaches a complete modded startup but clients are rejected, compare the server/client item versions and dependency sets rather than deleting the server world. If joining works yet specific maps, vehicles, or items disappear, treat that as a data-integrity stop: the package may have loaded under a different internal component or order without restoring the content the save expects.

Set stop and rollback rules for data-bearing mods

Rollback means restoring the complete stopped cache checkpoint—Server files, Multiplayer save, database, backups, and the recorded mod set—not merely pasting the old INI over a world already saved without content. Preserve Workshop downloads where licensing and platform behavior allow, but treat the manifest and world backup as the authoritative recovery pair. A missing publisher artifact may make a safe restart impossible until a compatible release returns.

• Stop before world save if the earliest error names a required item, internal ID, dependency, map, vehicle, profession, or other persisted content provider.
• Stop if a publisher removed or renamed an item and no documented migration/removal path exists.
• Stop if the copied test requires changing several Workshop IDs, internal IDs, and load order at once; split the change into attributable groups.
• Stop if the server and client caches cannot be proven to hold the same current item version.

Run a controlled mod acceptance matrix

For each dependency group, record Workshop item IDs, provided internal IDs, item update time, Build generation, load order, and the first clean startup log. Verify server acquisition, internal loading, no script/dependency errors, one matching-client join, and representative content in the copied world. Then console save and quit, restart, and verify that both content and client admission persist.

Promote the configuration only when every required group passes. Keep the prior manifest and checkpoint until players have completed normal sessions. Before future server updates, snapshot the cache and export both ordered lists; after the update, compare publisher compatibility and test the same matrix privately. This catches a renamed ID, changed dependency, or stale client cache before a public start writes a stripped-down world.