Troubleshooting and FAQ

Troubleshooting and FAQ

This page addresses common questions, error messages, and troubleshooting procedures for Project Zomboid Optimiser (PZO).

---

Dedicated Server Issues

Error: SteamAPI_Init() failed - Steam must be running

• Symptoms: When launching a dedicated server on Linux, Docker, or Pterodactyl, the server terminates immediately with:

  pzexe: SteamAPI_Init() failed
  Steam must be running to play this game (SteamAPI_Init() failed).
  Fatal Error
  

• Cause: In ProjectZomboid64.json, the "mainClass" field was modified (e.g. changed to com/pzoptimizer/server/PZOServerEntrypoint). The native Linux launcher executable (ProjectZomboid64 / pzexe) checks whether mainClass equals "zombie/network/GameServer". If mainClass is anything else, the launcher assumes it is booting a desktop game client and calls SteamAPI_Init(). On headless Linux servers without a running Steam client, this call unconditionally fails.
• Solution:
  1. Open ProjectZomboid64.json and ensure "mainClass" is kept strictly as:

     "mainClass": "zombie/network/GameServer",

  2. Load the PZO server engine as a Java Agent by adding "-javaagent:PZOServerEngine.jar" to the top of your "vmArgs" array instead.
  3. Ensure steam_appid.txt containing 108600 exists in the server root.

---

Dedicated Server OOMKilled by Host (Pterodactyl / Docker)

• Symptoms: The server starts, runs for a few minutes or hours, and is suddenly killed by the host node without a Java stack trace.
• Cause: -Xmx was set equal to or greater than the hosting container's total allocated RAM. The HotSpot JVM heap is only part of total memory usage; off-heap direct buffers, native C++ libraries (RakNet, FMOD), and thread stacks require additional memory.
• Solution: Reduce -Xmx so that at least 512MB to 1024MB remains unallocated for native processes. For example, on an 8GB container plan, set -Xmx7168m.

---

Client Issues

Main Menu Icon Shows "PZO Engine Inactive"

• Symptoms: The main menu loads, but the gear icon in the top-right is greyed out and says "PZO Engine Inactive".
• Checks:
  1. Check ProjectZomboid64.json: Open the file in your game folder and verify that "-javaagent:PZOptimEngine.jar" is present in "vmArgs".
  2. Check JAR Location: Confirm PZOptimEngine.jar is located in the same directory as ProjectZomboid64.json.
  3. Launch Method: Launch the game directly through Steam. If launching via a custom shortcut, ensure the working directory is set to your Project Zomboid installation folder.

---

Game Crashes on Startup with Black Screen

• Symptoms: Project Zomboid attempts to start, displays a brief black window, and closes.
• Checks:
  1. Check console.txt in C:\Users\<username>\Zomboid\ (Windows) or ~/Zomboid/ (Linux).
  2. If the error mentions Could not reserve enough space for object heap:
     • Open ProjectZomboid64.json.
     • Reduce -Xmx (e.g. change -Xmx16384m down to -Xmx8192m or -Xmx4096m).
  3. If using outdated graphics drivers, ensure OpenGL 3.3+ acceleration is enabled.

---

Linux / Steam Deck: "Permission Denied"

• Symptoms: Running ./pzo_optimizer.sh in the terminal outputs bash: ./pzo_optimizer.sh: Permission denied.
• Solution: Grant execute permissions to the script before running:

  chmod +x pzo_optimizer.sh
  ./pzo_optimizer.sh

---

Frequently Asked Questions (FAQ)

Does this require zombiebuddy?

No.

Do I need to use the Java mod here on Github?

Nope. If you only want to use the version found on the Steam Workshop that will work standalone for you. The Java extension is an optional more advanced performance booster for those who want it.

Is it compatible with (insert mod here)

Mostly yes, I don't know and havent tested for every mod out there and i really dont want to. Most mods should work with PZO including Zombiebuddy mods. However other performance mods should be used with caution as they could conflict in weird and unexpected ways.

Is it safe to add/remove mid save?

Yes, there should be no issues adding or removing PZO mid save.

Can I get banned on multiplayer servers for using PZO?

No. PZO utilizes standard JVM JavaAgent instrumentation (java.lang.instrument), which operates entirely within Java's officially supported runtime API. It does not modify game binaries (ProjectZomboid64.exe) or hook into protected operating system memory spaces.

Does PZO work on Build 41 as well as Build 42?

Yes. PZO is tested and compatible with both Build 42 (Stable) and Build 41 (Legacy). PZO features dynamically adapt to the game version detected at launch.

How do I completely uninstall PZO?

1. Delete PZOptimEngine.jar (or PZOServerEngine.jar) from your game/server directory.
2. In Steam, right-click Project Zomboid > Properties > Installed Files > Verify integrity of game files. Steam will verify and restore the default ProjectZomboid64.json.