Project Zomboid server lag: causes and fixes

A Project Zomboid server lags for one of five reasons, and they are easy to tell apart once you know where to look. Too many zombies alive in loaded areas. Players spread across the map so the server keeps several regions awake at once. A Java heap that is too small, so the server spends its time collecting garbage - or too large for the plan, so the container is stopped at its memory limit. Thousands of items and corpses that nobody cleans up. Or something periodic: a world save, a zipped backup of a big save folder, or a mod doing heavy Lua work on a timer. "Lag" that only some players see, while others are fine, is usually not the server at all.

This guide covers how a Zomboid server spends its time, how to find which of the five you have, and the settings that fix each one. The general settings file is covered in Project Zomboid server settings, and the sandbox options are explained one by one in Project Zomboid SandboxVars explained.

How a Zomboid server spends its time#

Zomboid's world is made of cells, and cells are made of chunks. The server keeps loaded the chunks around every connected player, and everything inside them is live: zombies, corpses, items on the floor, fires, vehicles, generators, crops. Outside those areas, the world is stored and mostly asleep, apart from coarse bookkeeping such as zombie migration.

Two consequences shape everything else.

Spread costs more than count. Ten players in one town load one area. Four players in four towns load four areas, each with its own zombies and objects. This is why player count is a poor predictor of Zomboid load in both directions, and why the same server can be fine on Saturday and miserable on Sunday with the same people online.

Clients do some of the work. In Build 41 multiplayer, much of the movement of zombies near a player is computed on that player's machine and synchronised through the server. That keeps the server lighter, but it means a player on a weak PC or a poor connection can make the zombies near them stutter and teleport for everyone standing nearby, while the server's own load looks fine.

The server is a Java process and its main simulation leans on one thread, so a fast core matters more than many slow ones. A second core still helps, because saving, networking and garbage collection happen alongside.

Finding which problem you have#

Before changing settings, spend an evening watching. On a panel host you have three useful sources: the memory and CPU graphs against your limits, the live console, and Zomboid/server-console.txt, which holds the full output of the current run.

The console also shows java.lang.OutOfMemoryError if the heap itself runs out, which is a different failure from the container limit and points at -Xmx being too small for the world.

A distinction worth holding on to: lag that everybody sees at the same moment is the server. Lag that one player sees, or that follows one player around, is a client or a connection. Latency, jitter and packet loss is the quickest way to tell a player which of those they have.

The Java heap: the setting most servers get wrong#

The server's memory is set in ProjectZomboid64.json in the server install, not in the ini:

{    "mainClass": "zombie/network/GameServer",    "classpath": ["."],    "vmArgs": [        "-Djava.awt.headless=true",        "-Xms3g",        "-Xmx6g",        "-XX:+UseZGC"    ]}

The real file has more arguments than this; change only the -Xms and -Xmx values and leave the rest. Recent Build 41 releases ship with the ZGC garbage collector already selected, which keeps pauses short; if your file has a different collector, leave it as shipped unless you know why you are changing it.

Two ways to get the heap wrong:

Too small. The heap fills, the garbage collector runs constantly to make room, and the server spends its time cleaning instead of simulating. You see regular stutters that get worse as the world grows, and eventually an OutOfMemoryError.

Too large for the plan. The heap is not the whole process. Thread stacks, the JVM's own structures and native memory sit outside it, and the container limit counts everything. Set -Xmx equal to the plan and the process outgrows its container while Java still believes it has room. On RE:NODE the container is then stopped and restarted clean rather than allowed to swap, so you see an abrupt restart with no error in the log - and an unsaved one.

Seventy to eighty per cent of the limit is the rule. If a server at that ratio still hits the limit, it needs a bigger plan rather than a bigger heap. CPU vs RAM for game servers covers telling which resource is short before you pay for either.

Zombie population#

Zombies inside loaded areas are the single biggest simulation cost, and population is controlled in the sandbox file:

SandboxVars = {    Zombies = 4,    ZombieConfig = {        PopulationMultiplier = 1.0,        PopulationStartMultiplier = 1.0,        PopulationPeakMultiplier = 1.5,        PopulationPeakDay = 28,        RespawnHours = 72.0,        RespawnMultiplier = 0.1,        RedistributeHours = 12.0,        FollowSoundDistance = 100,        RallyGroupSize = 20,    },}

PopulationMultiplier scales everything. PopulationPeakMultiplier and PopulationPeakDay mean population rises over the first weeks, so a server that runs well on day 3 can struggle on day 28 without any setting changing. If you see a gradual slowdown over the first month that restarts do not fix, check where you are against the peak day.

Reducing load without making the game feel empty:

• Lower the peak, not the start. A PopulationPeakMultiplier of 1.2 instead of 1.5 keeps the opening tension and takes the edge off the later weeks.
• Turn respawn down or off. Respawn refills cleared areas, which keeps the number of zombies in loaded areas high for the whole life of the server. RespawnHours = 0 stops it entirely.
• Smaller rally groups. RallyGroupSize controls how many zombies group together when they migrate. Very large hordes converging on a base are a spike the server feels.

Raising population on a busy server is the most reliable way to make it lag. If the group wants more danger, zombie speed and toughness in ZombieLore are cheaper than numbers.

Later Build 41 ini files also include ZombieUpdateMaxHighPriority, ZombieUpdateDelta, ZombieUpdateRadiusLowPriority and ZombieUpdateRadiusHighPriority, which control how often and how far zombie state is synchronised to clients. They trade smoothness for bandwidth and CPU. Leave them at the values your server generated unless you have measured a problem they would fix and you change one at a time.

Players, vehicles and spread#

Since spread is the cost, a few settings reduce how much world each player drags into memory.

SpeedLimit exists largely because of chunk streaming. A player driving at full speed crosses chunks faster than the server comfortably loads them, which shows as stutter for the driver and load for everyone. The default is a deliberate compromise; raising it makes cross-map driving worse.

The other lever is social rather than technical: servers built around a shared town or a few nearby bases run lighter than servers where every player claims a corner of the map. On a public server that is not yours to dictate. On a friends' server, it is worth knowing.

Items, corpses and accumulation#

Everything on the floor of a loaded area is part of the simulation and has to be saved. A long-running server accumulates: the corpses from a week of fighting outside a base, the clothes and junk people drop, the furniture they dismantle.

The defaults keep corpses for nine in-game days and remove only a few item types from floors. On a busy server, corpses are the bigger problem: a base that has fought off a horde can have hundreds lying outside it. Lowering HoursForCorpseRemoval to something like 72 helps more than most settings in this guide, at the cost of a little atmosphere.

WorldItemRemovalList with ItemRemovalListBlacklistToggle set to true removes every floor item except the ones you list, which cleans up aggressively. It also removes things players dropped deliberately, so announce it.

ItemNumbersLimitPerContainer exists for the hoarder who puts four thousand nails in one crate. A container with a huge item list is expensive every time someone opens it or the chunk is saved.

Saves, backups and periodic stutter#

A stutter at regular intervals is almost always the server writing to disk.

SaveWorldEveryMinutes=15BackupsPeriod=0BackupsOnStart=trueBackupsCount=5

SaveWorldEveryMinutes writes the world on a timer; 0 leaves saving to the server's own rhythm and shutdowns. A short interval on a large world means a short stall often. BackupsPeriod is worse on a big server: it zips the entire save folder every so many minutes, and on a world measured in gigabytes that is a long, heavy job running while people play. Leave it at 0, keep BackupsOnStart=true, and take real backups at a quiet hour with a restart.

On RE:NODE the Schedules tab can do exactly that: a console command warning players, a delay, /save, a restart, then a backup, at an hour when nobody is on. Backups taken that way are stored off the machine, which Zomboid's own zips are not. Restart schedules that help covers picking the hour.

Mods#

Mods are where performance problems hide on a modded server. Zomboid mods are Lua, and Lua code that runs every tick, every minute or on every player action adds up across a long mod list. Map mods add their own cost: more cells with more objects, often more detailed than vanilla.

What helps:

• Remove mods nobody uses. A long list collected over months usually contains several.
• Suspect anything that runs on a timer: weather systems, spawners, NPC frameworks, economy mods that scan containers.
• Bisect. If a modded server lags and vanilla does not, remove half the mods on a copy of the server, test, and repeat. It is slow and it is the only method that gives an answer.
• Read the console after updates. A mod that throws errors repeatedly is slower than one that works, and errors scroll past in their hundreds.

Project Zomboid server mods covers load order and the workshop, and keeping a modded server clean the general hygiene.

Restarts#

A daily or twice-daily restart is normal practice for Zomboid servers, and for good reason: memory use and accumulated objects grow over uptime, and a restart puts the server back to a clean start. Pick an hour when the fewest people are on, warn them in chat beforehand, and save before stopping. A restart costs a minute or two; a server that has been up for a week and is collecting garbage every few seconds costs everyone's evening.

Troubleshooting#

The server restarts suddenly with nothing in the log. It reached the plan's memory limit. Lower -Xmx to about three quarters of the plan, and if that leaves too little heap, move up a plan.

Stutter every few minutes, like clockwork. Saving or zipped backups. Check SaveWorldEveryMinutes and set BackupsPeriod=0.

Zombies teleport around one player. That player's connection or PC. Their client is computing zombie movement near them. Check their ping and frame rate.

The server was fine for a month, then slowed. Population peaking (PopulationPeakDay), corpses and items accumulating, or the save growing. Look at each in turn.

A base is laggy for everyone who visits. Corpses outside it, overfilled containers, or a very complex build. Clean the corpses and check ItemNumbersLimitPerContainer.

Lag started after adding a mod. Remove it on a copy and test. If that fixes it, look for an alternative or a configuration option in the mod that reduces its work.

Players are kicked for high ping. PingLimit in the ini is the threshold. Raising it lets distant players stay, and they will still lag the zombies around them.

FAQ#

How much RAM does a Project Zomboid server need?

Three gigabytes for a small group in one area, 4-6 GB for eight to sixteen players spread out, and 8-10 GB for a large modded server. Set -Xmx to about three quarters of the plan, never all of it.

Why does the server lag when we split up?

Each player keeps the area around them loaded and simulated. Players in four towns means four areas of zombies, items and objects live at once. The same people together in one town cost far less.

Does more CPU fix Zomboid lag?

Only if the CPU graph shows the server at its share. Many Zomboid lag complaints are memory, accumulation or one player's connection, none of which more CPU changes.

Should I lower the zombie population?

If the server struggles with zombies in loaded areas, lowering the peak multiplier or turning off respawn helps more than lowering the start population. Zombie speed and toughness add difficulty without adding load.

Are corpses really a performance problem?

On busy servers, yes. Each corpse is an object in the world that is simulated while loaded and saved with its chunk. Hundreds outside a base add up. Lowering HoursForCorpseRemoval is one of the most effective changes available.

Does PauseEmpty help performance?

It stops the world when nobody is online, which saves CPU during empty hours and stops things decaying. It does nothing while people are playing.