Mods not working on your Project Zomboid server
When mods download but do not work, the first useful error usually tells you where to look. Use this guide to check the right server and profile, fix the mod list, and test without risking your world.
- Confirm the server address
- Find the first relevant error
- Check the build and mod IDs
- Back up and isolate the failing mod
Am I joining the right server?
Section titled “Am I joining the right server?”Compare the IP address and port in your saved Favorites entry with the address shown for this server in the panel. A saved entry for another server can make a correct mod change look broken. If they differ, correct the entry and follow the connection guide before downloading anything again.
The server does not start after adding mods
Section titled “The server does not start after adding mods”Open Console in the panel. The server downloads Workshop items at startup. Wait for the download and startup messages to progress; startup is complete when the console says SERVER STARTED. That line does not prove every mod loaded. If progress stops, inspect .cache/Logs/ through Files, keep the first relevant error and contact support if it remains stuck. There is no fixed download time that means failure.
Check Startup → Server Name to identify the active profile; its default is Pterodactyl. In Files, open .cache/Server/<ServerName>.ini and compare WorkshopItems= (numeric Workshop item IDs) with Mods= (the Mod IDs inside those items). One item can contain multiple Mod IDs. Check each mod author’s requirements and add missing dependency items and their Mod IDs. A Workshop collection only groups items; a bundled modpack may have several Mod IDs, while separate mods need their own Workshop IDs. Use the installation guide for the PZ Mods workflow and manual format.
If you see required mod ... not found, check the named Mod ID, its Workshop item and dependencies first. The Indie Stone forum example shows that message when a dependency is missing. A Build 42 server report also shows downloaded items alongside a required mod ... not found warning, so a completed download alone is not a successful load.
The server runs, but players get “required mod not found” or a mod mismatch
Section titled “The server runs, but players get “required mod not found” or a mod mismatch”First repeat the address check above. Then compare the player’s game build with the server build. In Startup, an empty Steam Branch means Build 42 stable; legacy41 means Build 41. Switching branches requires a server reinstall. Back up first: Build 41 and Build 42 saves are not interchangeable. Steam Auto Update updates the server build on each start when enabled; it does not mean Workshop changes take effect while the server is running.
For a named missing mod, compare the exact Mod ID with the active profile and the author’s current Workshop page. Include its dependencies. If PZ Mods lacked Mod ID or Map Folder metadata, let the server download the items, then open Installed and run Sync Mods/Map again. Restart and check both the console and one player’s join. If the error names a Workshop version mismatch after a mod update, restart the server so it can load the updated item; ask the player to reconnect after startup finishes. Do not repeatedly clear the player’s downloads while the server still uses an older version.
Mods show as loaded, but do nothing in game
Section titled “Mods show as loaded, but do nothing in game”Check the mod author’s Build 41 or Build 42 support, dedicated-server instructions, required libraries and where its feature should appear. A mod may download and even appear in a list without its intended feature working. Check that you edited the profile selected in PZ Mods, and test with one player on the correct server after SERVER STARTED. If a mod changes a map or existing world, read its save requirements before testing it on that world.
If the cause is still unclear, make and verify a backup, then disable half of the suspect mods in the active profile. Keep the backup and a copy of the original WorkshopItems= and Mods= lists. Restart and test with one player. Continue halving the failing group until you identify an item or dependency; restore the original lists if the test makes no progress. Do not delete saves, the whole Workshop cache or all player files as a first step.
A Workshop mod updated. Do I need to restart?
Section titled “A Workshop mod updated. Do I need to restart?”Yes. A running server cannot use the newly downloaded mod version until it restarts. Plan a restart, watch Console for download progress and SERVER STARTED, then test a join. Check on a schedule that fits your server; this guide does not assume an automatic restart. The Indie Stone mismatch report records players being rejected after a Workshop update until the server restarted.
Is a Workshop collection the same as one modpack?
Section titled “Is a Workshop collection the same as one modpack?”No. A collection is a list of Workshop items. One item may contain multiple Mod IDs, and a bundled modpack may still need dependencies from separate items. Check each author’s instructions, then sync the active profile through PZ Mods.
What should I send support?
Section titled “What should I send support?”Send the exact error, the time it appeared, the server and client builds, the server address and port, the active Server Name, the relevant Workshop IDs and Mod IDs, and a short console fragment around the first error. If startup stalls, attach the relevant file from .cache/Logs/. Never send Admin Password or other passwords. Create a ticket with these details.