Nexardo

Project Zomboid Field guide

Troubleshoot Project Zomboid Mod Conflicts: Reading console.txt and Red Error Box Fixes

Troubleshooting Project Zomboid mod conflicts: analyzing STACK TRACE dumps in console.txt, correlating Workshop IDs, and structuring dependency order in servertest.ini.

EugenePublishedUpdatedReading time3 min
Troubleshoot Project Zomboid Mod Conflicts: Reading console.txt and Red Error Box Fixes

The dreaded red error counter box in the bottom right corner of the screen is an infamous sight for any Project Zomboid modded server administrator. This indicator warns that an unhandled Lua exception has broken a background tick routine. On dedicated servers, script collisions cause frozen container inventories, invisible zombie textures, desynchronized animations, and fatal crashes when players venture into specific map sectors.

This practical troubleshooting guide explores Project Zomboid's runtime logging architecture, decoding call stacks inside console.txt, mapping broken script paths to Steam Workshop IDs, and restructuring mod execution order inside .ini configurations.

Server Logging and Parsing Lua STACK TRACE Dumps#

When a mod script encounters an invalid state or missing prototype, the underlying Kahlua Java Lua runtime catches the exception and outputs a diagnostic stack dump into ~/Zomboid/Server/<ServerName>_console.txt (or client-side ~/Zomboid/console.txt).

Filter the active log file to pinpoint runtime exceptions:

bash
tail -n 100 ~/Zomboid/Server/servertest_console.txt | grep -E "STACK TRACE|Callframe at|ERROR:"

A standard error block details the execution failure:

text
ERROR: General     , 1730764800000> Exception in script: ModFile.lua
STACK TRACE
Callframe at: media/lua/shared/OffendingScript.lua:142 in function: updateContainers

This output isolates the exact offending script name (OffendingScript.lua) and line number within the mod structure.

Identifying Problematic Packages via Workshop Directory Matching#

Because dedicated servers cache downloaded Steam items using numeric folder hierarchies, administrators must correlate the Lua script name with its parent Workshop ID:

bash
find ~/Zomboid/SteamApps/workshop/content/108600/ -name "*.lua" | grep "OffendingScript"

The output returns a path such as .../content/108600/2849104821/mods/VehicleFramework/media/lua/.... The numeric sequence represents the Steam Workshop ID, while the directory under mods/ provides the canonical Mod ID.

Auditing Dependency Order in servertest.ini#

The two most prevalent sources of persistent server errors are improper dependency ordering and conflicting map coordinate overwrites:

  • Framework Precedence: Core libraries (including tsarslib, ModOptions, ItemTweakerAPI) must precede all dependent gameplay mods in the Mods= string.
  • Custom Map Hierarchy: Under the Map= directive, custom community cities must always appear before the base game Muldraugh, KY entry.

Inspect the current server configuration string:

bash
grep -E "Mods=|Map=|WorkshopItems=" ~/Zomboid/Server/servertest.ini

Safely Disabling Broken Workshop Extensions#

If a mod has been abandoned by its creator and repeatedly crashes the game loop, deactivate it by stripping its Mod ID from Mods= and numeric ID from WorkshopItems=:

bash
sed -i 's/Mods=BrokenMod;/Mods=/' ~/Zomboid/Server/servertest.ini && sed -i 's/WorkshopItems=12345678;/WorkshopItems=/' ~/Zomboid/Server/servertest.ini

Following modification, restart the server daemon and stream operational logs to confirm clean initialization:

bash
sudo systemctl restart zomboid && sudo journalctl -u zomboid -f

For survivor communities wanting to run expansive modlists without endless terminal debugging or corrupted world chunks, managed Project Zomboid server hosting delivers automated Workshop dependency checking and automated save rollbacks.

Sources#