This guide covers advanced mod troubleshooting for Project Zomboid servers hosted with Legion Hosting. If you have not yet installed mods, start with the basic mod installation guide first. This article addresses the most common mod-related issues seen across Legion Hosting support tickets, including WorldDictionary corruption, mod format errors, load order conflicts, and version mismatches between server and client.

Before You Begin

• Log in to GPanel and select your Project Zomboid server.
• Stop your server before making any configuration or file changes.
• Back up your world save folder (/.cache/saves/multiplayer/) via SFTP or GPanel before attempting any fix. See the SFTP guide if you are unfamiliar with file transfers.
• Have your server's .ini file path ready: /.cache/server/<servername>.ini (e.g., servertest.ini).

1. Mod Format Errors (B42 vs B41)

The most common reason mods fail to load is an incorrect format in the Mods= line of your server's .ini file. Build 42 and Build 41 use different syntax, and mixing them up will silently fail to load your mods.

B42 Format (Current Default)

Build 42 requires a backslash prefix before each Mod ID in the Mods= line:

Mods=\ModID1;\ModID2;\ModID3;

The DLMP format combines Workshop IDs and Mod IDs with a backslash separator:

Mods=2392987841\ModID1;1550458773\ModID2;2786383654\ModID3;

The WorkshopItems= line uses the same semicolon-separated format on both builds:

WorkshopItems=2392987841;1550458773;2786383654

B41 Format (Legacy)

Build 41 uses plain semicolon-separated Mod IDs with no backslash:

Mods=ModID1;ModID2;ModID3

How to Fix

1. Open /.cache/server/<servername>.ini in the GPanel File Manager.
2. Find the Mods= line and check the format against the examples above.
3. If the format is wrong for your build version, correct it. Use the Legion Hosting Mod Organizer to generate correctly formatted lines automatically.
4. Save the file and start the server.

2. WorldDictionary Corruption

The WorldDictionary is a file (WorldDictionary.bin) that maps item names to internal numeric IDs. When mods are added or removed, the dictionary can become corrupted, causing the server to crash on startup with a WorldDictionaryException.

Symptoms

• Console or debug.log shows WorldDictionaryException or WorldDictionary errors.
• Server crashes immediately during startup, specifically during world loading.
• The crash started after adding, removing, or updating mods.

Understanding the Risk

Recovery Steps

1. Stop your server in GPanel.
2. Back up your entire save folder via SFTP: download the full /.cache/saves/multiplayer/<YourWorldName>/ directory to your local machine.
3. First, try simply reverting the mod change that caused the error. If you just added a mod, remove it from both Mods= and WorkshopItems= in the .ini file. If you just removed a mod, add it back. Start the server and see if the crash is resolved.
4. If reverting the mod change does not work, connect via SFTP and navigate to /.cache/saves/multiplayer/<YourWorldName>/.
5. Delete WorldDictionary.bin.
6. Start the server. Project Zomboid will regenerate the dictionary on startup.
7. Join the server and inspect the world for corrupted items, missing vehicles, or broken inventories. If the world is severely damaged, restore from the backup you created in step 2.

3. Authentic Z Mod Conflicts

Authentic Z is one of the most popular Project Zomboid mod collections, but it is a frequent source of support tickets because it contains multiple sub-mods that conflict with each other.

The Rule

Common Mistakes

• Adding both Authentic Z - Current and Authentic Z - Litemode at the same time.
• Adding Authentic Z sub-mods that are designed for singleplayer alongside the multiplayer version.
• Not realizing that different Authentic Z sub-mods share the same Workshop ID but have different Mod IDs, so the Workshop download succeeds but the server loads conflicting mod files.

How to Fix

1. Open /.cache/server/<servername>.ini in the GPanel File Manager.
2. Search the Mods= line for every entry containing Authentic or AuthenticZ.
3. Keep only one Authentic Z sub-mod (recommended: Authentic Z - Current). Remove all other Authentic Z entries from both the Mods= and WorkshopItems= lines.
4. Save the file and restart the server.

4. Linux Case-Sensitivity Issues

Legion Hosting servers run on Linux, where file and folder names are case-sensitive. A file named MyMod.lua and mymod.lua are treated as two completely different files. This causes problems when mod authors develop on Windows (case-insensitive) and their mods contain mismatched file references.

Symptoms

• A mod works perfectly in singleplayer on your Windows PC but fails on the server.
• Console or debug.log shows FileNotFoundException or can't find file errors referencing a Lua script or texture inside a mod.
• The error points to a file that does exist in the mod folder, but with different capitalization (e.g., the code references Items.txt but the actual file is named items.txt).

How to Diagnose

1. Check the console or /.cache/Logs/ log files for the exact file path mentioned in the error.
2. Connect via SFTP and navigate to the mod's folder at /steamapps/workshop/content/108600/<WorkshopID>/.
3. Compare the file names on disk with the file name referenced in the error message. Look for capitalization differences.

How to Fix

• If you can rename the file: Connect via SFTP and rename the file to match the capitalization expected by the mod's code. Note that this fix will be overwritten if the mod updates on Steam Workshop.
• If the issue is in the mod itself: Report the bug to the mod author on the Steam Workshop page. Mention that the file reference has a case mismatch and that it fails on Linux servers. Many mod authors are not aware of Linux case-sensitivity.
• As a workaround: Check the mod's Workshop page comments — other Linux server operators may have posted a fix or a compatible fork of the mod.

5. Mod Load Order Problems

Project Zomboid loads mods in the order they appear in the Mods= line. Some mods depend on other mods being loaded first. If a dependency is loaded after the mod that requires it, the dependent mod may fail silently or cause errors.

Symptoms

• Mod features are partially working — some items or systems from a mod are present but others are missing.
• Console shows NullPointerException or attempt to index a nil value errors referencing a mod's Lua scripts.
• Errors only appear when a specific combination of mods is installed, but each mod works fine individually.

How to Fix

1. Check each mod's Steam Workshop page for a "Required Mods" or "Load Order" section. Many mod authors specify which mods must be loaded before theirs.
2. Open /.cache/server/<servername>.ini and find the Mods= line.
3. Reorder the entries so that dependency mods appear before the mods that require them. For example, if Mod B requires Mod A, the line should read Mods=\ModA;\ModB; (B42 format).
4. Framework and library mods (such as ModFramework, TsarLib, or Shark's Mod Utils) should always be listed first in the Mods= line.
5. Save the file and restart the server.

6. Server Crashes After Adding Mods

If your server was running fine and crashes after adding one or more mods, the new mod is likely the cause. This section walks through isolating the problem mod.

Step-by-Step Isolation

1. Stop the server in GPanel.
2. Open /.cache/server/<servername>.ini in the File Manager.
3. Note all the mods you just added. Remove all of them from both the Mods= and WorkshopItems= lines.
4. Start the server. If it starts successfully, the problem is in one of the mods you removed.
5. Add the mods back one at a time, restarting the server after each addition. When the crash returns, the last mod you added is the cause.
6. Once identified, check the mod's Workshop page for:
   • A note about B42 compatibility — many B41 mods have not been updated for B42.
   • Known conflicts with other mods you are running.
   • Required dependency mods that you may not have installed.

Reading the Crash Log

Before performing the isolation process, check the crash log — it often points directly to the problem mod:

1. In GPanel, open the Console tab and scroll to the end of the output.
2. Look for STACK TRACE, Exception, or ERROR lines.
3. The lines immediately above the stack trace typically reference a mod filename or Mod ID — this tells you which mod triggered the crash.
4. For more detail, open the full log file via SFTP at /.cache/Logs/ and check the most recent DebugLog-server.txt or debug.log file.

7. Mod Version Mismatches (Server vs Client)

Project Zomboid requires the server and all connected clients to have the same version of every mod. If a mod updates on the Steam Workshop and the server downloads the new version but a player still has the old version cached (or vice versa), connection failures or crashes will occur.

Symptoms

• Players get a "Mod mismatch" or "Version mismatch" error when trying to connect.
• Some players can connect but others cannot — the ones who cannot connect have a different mod version cached locally.
• The server was working fine, then a mod updated on Steam Workshop and suddenly some players cannot join.
• Players see missing textures, items, or broken UI elements from mods that were recently updated.

Fix for Server Operators

1. Stop the server in GPanel.
2. Start the server again. On startup, the server re-downloads the latest versions of all Workshop mods. This ensures the server is running the newest version.
3. If the server still has an old version cached, connect via SFTP and delete the specific mod's Workshop cache folder at /steamapps/workshop/content/108600/<WorkshopID>/. Restart the server to force a clean download.

Fix for Players

Players who cannot connect due to mod version mismatches should:

1. Open Steam and navigate to Library → Project Zomboid.
2. Right-click Project Zomboid, select Properties → Local Files → Verify Integrity of Game Files.
3. Also navigate to the Steam Workshop folder for Project Zomboid on their local machine and delete cached mod files to force a re-download.
4. Launch the game and connect to the server again.

8. Clearing the Steam Workshop Cache

If multiple mod issues persist and you suspect the Workshop download cache is corrupted, you can force a complete re-download of all Workshop mods.

1. Stop the server in GPanel.
2. Connect via SFTP and navigate to /steamapps/workshop/.
3. Delete the entire workshop/ folder (or its contents).
4. Start the server. Steam will re-download all Workshop items from scratch.
5. Watch the GPanel Console to confirm all mods finish downloading before the server begins world loading.

Quick Diagnostic Reference

Still Having Mod Problems?