Project Zomboid GuideBuild 42.21 StableUpdated September 30, 2026
Project Zomboid GuideMaps · Mods · Multiplayer · Servers

troubleshooting

Mod Dependency Diagnosis

Quick Answer

Start from the failing item and walk its whole chain before touching anything else. The captured Build 42 sample shows the shapes chains take: CD: Belgian Malinois requires Companion Dogs 0.8.0+ (versioned requirement), pz3d requires ZombieBuddy (3619862853), Hug the Plushie requires item 3749026793 plus a restart and a load-after note. For each link confirm: downloaded, enabled in the same context (save, host, or server — where WorkshopItems and Mods are separate fields), current for your patch, and ordered as documented. Then retest the smallest complete chain before restoring the full list.

Table of Contents

Dependency chain record

Start from the failing Workshop item and follow every requirement before touching your whole mod list. The smallest complete chain gives you a clean failure boundary.

StageCaptureYou get
RootTitle, Workshop ID, patch, exact symptomOne named failing entry
ChainEvery required item or frameworkA complete dependency graph
ContextSave, host, or dedicated-server activationOne test context with matching IDs
RetestSmallest complete chainThe first failing dependency or a clean pass
RestorePrevious list and save copyA way back before you replace files

Real chains from the captured sample

Three Build 42 items with hard requirements, captured 2026-09-29 — enough to see every shape a dependency can take.

Failing itemThe recorded chainThe trap in it
CD: Belgian Malinois (3808688990)Requires Companion Dogs 0.8.0 or newer; full restart after enabling; intended for dedicated and co-op serversA versioned requirement: 0.7.x installs fine and still fails. Check the version number, not just the name, and budget for the restart before testing
pz3d (3807334881)Requires ZombieBuddy (item 3619862853); single-player only, WIPA framework dependency on a work-in-progress core — the framework's update cycle now owns your install. Highest-blast-radius chain in the sample
Hug the Plushie! (3807099610)Requires item 3749026793; restart after enabling; loads after other affected modsA dependency with ordering attached: enabling both items but ignoring the load-after note produces an intermittent failure that looks like random breakage

The context layer, where chains go quiet

A chain can be fully subscribed and still inactive — because activation is per context, and servers split it across two fields.

Context one: the save. A mod enabled globally is not automatically on for an existing save — the PZwiki flow (Load > your save > More > Choose Mods) exists because saves keep their own selection. A dependency chain that's half-enabled for the save produces exactly the missing-mod symptoms that send people uninstalling the wrong item. The same logic applies in reverse: a mod you 'removed' can still be active on an old save.

Context two: the server. WorkshopItems= and Mods= are separate configuration fields, a Steam Support response says server mods must be enabled in both, and the dedicated-server reference (42.20.0-marked) separates them again. A dependency installed via WorkshopItems but not enabled via Mods is subscribed-but-inactive on the server — and the failure appears on the client side, far from the field you forgot. On a server, walk the chain field by field, on both sides.

The retest discipline closes it: install the smallest complete chain — the failing item plus only its requirements — and test that, before restoring the rest of the list. Half the 'it was never the dependency' conclusions come from testing a full list where three other items mask or mimic the failure. The smallest chain gives the failure a clean boundary, and the written record of that test is what turns a bad evening into a documented quirk.

Reference data

Start with the Workshop item that fails, then follow every required item in the chain — keeping the save, host, or dedicated-server context fixed.

StepCaptureResult
Root itemTitle and Workshop IDThe failing item is named exactly
Required itemEvery dependency listed by the authorThe chain is complete before retest
ActivationSave, host, or dedicated-server contextThe same chain is enabled in one context
RetestSmallest complete chainThe first failing dependency is isolated
RollbackPrevious item list and save copyThe diagnosis can be reversed without replacing the live profile

FAQ

How do I find a mod's dependencies?

The author's Workshop description — the captured sample lists them inline: CD: Belgian Malinois needs Companion Dogs 0.8.0+, pz3d needs ZombieBuddy (item 3619862853), Hug the Plushie needs item 3749026793. Open every item in the chain too: requirements can recurse, and each link has its own build target and update cycle.

Why does a mod fail even though its dependency is installed?

Four recorded reasons: the version is below the requirement (Companion Dogs 0.7.x installs fine but Belgian Malinois needs 0.8.0+); the restart clause wasn't followed (Belgian Malinois and Hug the Plushie both require one after enabling); the load-order note was ignored (Hug the Plushie loads after other affected mods); or the context is split — a save keeps its own mod selection, and servers need both WorkshopItems and Mods enabled.

What is the smallest complete chain?

The failing item plus only its hard requirements — nothing else. Test that in isolation and the failure gets a clean boundary: it either reproduces (the chain is the problem, halve it further) or disappears (something outside the chain was masking or mimicking it). Retesting the full list first is how the wrong item gets uninstalled.

Do dependencies work differently on servers?

Yes — activation is split across two fields. WorkshopItems= and Mods= are separate server settings, and a Steam Support response says server mods must be enabled in both. A dependency present in one field but not the other is subscribed-but-inactive, and the failure surfaces on the client side, far from the field you forgot. Walk the chain field by field, server and client both.