Guides

Fix mod dependency and 'mod is missing' errors

Most 'server won't start' mod problems trace back to a handful of causes. Here is how to find and fix each one, and how to catch them before you boot instead of after.

The usual causes

  • A missing Workshop item. A mod is enabled in Mods=, but the item that provides its dependency was never added to WorkshopItems=, so it never downloaded.
  • An unknown or misspelled mod ID. A value in Mods= does not match any mod ID that actually shipped, often a typo or the wrong one of an item's several mod IDs.
  • A delisted or private item. The Workshop item was removed or made private, so it can no longer download.
  • A bad load order. A mod loads before the framework it requires. See load order.
  • A map problem. A map mod is missing from Map=, or the base map is not last.

Diagnosing them

The server log names the mod it choked on, but not always the reason. Work through the list above: confirm every enabled mod ID has a matching Workshop item downloaded, cross-check each Mod ID: against the Workshop description, and make sure frameworks come first. For a delisted item, the Workshop page itself will be gone or private.

Catch them before you boot

Rather than restart the server and read logs on every change, validate the config first. pzmod's dry-run validation checks the whole config without writing anything and flags:

  • missing dependencies,
  • unknown or misspelled mod IDs,
  • delisted or unavailable Workshop items,
  • and a bad map order.

It runs from the terminal app or as a scriptable command that exits non-zero on errors, so you can even gate a server restart on it in CI:

pzmod validate

Fix what it flags, save (a timestamped backup is taken first), and boot with confidence.

Do it automatically with pzmod

pzmod is a free, open-source terminal app and CLI that handles all of this for you: search the Workshop, resolve dependencies, order your mods, and validate everything before you boot, all while keeping your servertest.ini byte-for-byte intact.

curl -fsSL https://pzmod.dev/install.sh | bash

See how pzmod works →