What to do when a mod update breaks your server

Stop the server so it is not crash-looping. Open the newest crash report and find the first line that names something which is not the game. Sort the mods folder by modification time and look at the top. Put the previous version of that file back. Start, confirm, and only then decide whether you wanted the update at all. That is the whole procedure, it takes about ten minutes, and it works because the pattern is always the same: nothing changed, and the server stopped working, which means something did change and the job is to find which - not to reinstall everything.

The rest of this post is how to do each of those steps when the answer is not obvious, plus the part nobody does until it has cost them an evening: arranging things so the next update cannot do this.

Ten minutes to a working server#

In order, and do not skip the first one.

1. Stop the server properly. A crashing server restarts, crashes, restarts, and each cycle rotates away a little more of the evidence. It can also get you into trouble: RE:NODE's crash watcher polls every two minutes for uptime that went backwards, and three restarts in an hour raises a warning and opens a ticket automatically, with six in an hour leading to suspension. Restarts you asked for are not counted, so stopping it yourself is both the correct diagnostic move and the one that keeps the server out of the loop. Why your game server keeps restarting covers the other causes of the same symptom.
2. Grab the evidence before it rotates. Download the newest file from crash-reports/, or BepInEx/LogOutput.log, or the console output from the last clean start up to the failure. Keep it even after you fix the problem.
3. Read the crash report from the top, not the bottom. The first line naming something that is not the game or the loader is your suspect.
4. Check the timestamps. ls -lt in the mods or plugins folder, or sort by date in the file manager. The newest file is almost always the one.
5. Put the previous version back. Keep the old jar; that is why you keep it. If you did not keep it, the mod's own release page has every prior version.
6. Start, and read the start-up banner. Confirm the version that loaded is the one you put back, and that the mod count matches what it was yesterday.
7. Decide about the update separately, tomorrow, on a copy. It is not urgent now.

Reading the crash report#

Minecraft writes crash reports to crash-reports/crash-2026-09-21_18.30.11-server.txt as well as to the console. The structure is consistent and only three parts of it matter.

The Description line at the top says what the game was doing when it died: ticking an entity, loading a world, initialising the mod system. That tells you which phase failed, which narrows the list of suspects enormously - a crash during mod loading is a dependency or version problem, a crash while ticking an entity is a gameplay bug in a specific mod.

The stack trace underneath is read from the top down. It is a list of the method calls that were in progress, most recent first, and the package names are the useful part:

java.lang.NoSuchMethodError: 'void com.example.lib.Registry.register(...)'    at com.someone.theirmod.ModInit.onInitialize(ModInit.java:44)    at net.fabricmc.loader.impl.FabricLoaderImpl.invokeEntrypoints(...)    at net.minecraft.server.Main.main(Main.java:112)

The first line names the error. The second line names com.someone.theirmod, which is not the game and not the loader, so that is the mod to look at. The lines below it are the machinery that called it and are rarely interesting. On Forge and NeoForge the report often prints a suspected mod near the top as well; treat that as a hint rather than a verdict, because the mod that crashed is frequently the victim of a library that changed underneath it.

The mod list at the bottom of the file is the thing to keep. It is a complete inventory of what loaded and at what version, which is exactly what you need to compare against yesterday's working start-up. This is the single best argument for keeping start-up logs, which logs worth keeping makes at more length.

Fabric is the friendliest of the loaders here. When the problem is versions rather than code, Fabric Loader refuses to start and prints a plain-English resolution error naming the mod, the dependency and the version it wanted. Read it literally; it is usually correct and it usually tells you the exact fix.

For Valheim and other Unity games, the equivalent file is BepInEx/LogOutput.log, and the same rule applies: find the first [Error or [Warning line that names a plugin rather than BepInEx itself. Valheim mods with BepInEx on a server covers the layout.

What the error actually means#

Java error names look interchangeable and are not. Each one points at a different fix.

On Paper and Spigot the wording differs but the logic is identical. org.bukkit.plugin.UnknownDependencyException: Unknown dependency Vault means a plugin declared depend: [Vault] in its plugin.yml and Vault is not there or failed first. A warning that a plugin was built for an older api-version is usually survivable; an outright load failure is not.

The important habit: when several plugins fail, fix the earliest failure in the log first. Failures cascade, and four of the five messages are frequently consequences of the first.

The six ways a mod update breaks a server#

Nearly every case fits one of these, and recognising the shape saves the diagnosis.

A dependency moved. The mod updated and now wants version 5 of a library while you have version 4, or the other way round. This is NoSuchMethodError territory and by far the most common cause. The fix is to update or downgrade the library to what the mod's release notes ask for.

The loader or game version changed. A modpack that auto-updated its Forge, NeoForge or Fabric Loader version, or a game update that went through overnight. Everything breaks at once and the crash happens during loading rather than during play.

Client and server fell out of step. The server updated and players did not, or the reverse. The symptom is not a crash at all: the server runs happily and everyone is kicked at connection, or desyncs shortly after. Every player needs the same mod at the same version, and this is why a modded server should not update on the day of a game patch.

A config schema changed. The new version reads a key that is not in your config, or silently ignores one that has been renamed, and the server starts but behaves wrongly. Check whether the mod rewrote its own config file - the timestamp on the config directory answers it.

Workshop content updated itself. For Steam Workshop games this is the classic. Project Zomboid, Garry's Mod, DayZ and Arma all pull workshop items on start, so "nothing changed" is simply false: the server downloaded a new version of somebody else's mod while you were asleep. Steam Workshop mods on dedicated servers explains how those downloads actually work.

Two mods now want the same thing. Mixin conflicts, two mods registering the same block ID, two chat plugins both cancelling the event. These appear after an update because the update started touching code the other mod had already patched. This is the only category where rolling back one file may not be enough.

Putting the old version back#

Where the files live, and what else has to move with them:

Finding the file that changed is a one-liner in either direction:

$ ls -lt mods/ | head -10$ find mods plugins -name "*.jar" -newermt "-2 days" -printf "%T+ %p\n" | sort

In a panel file manager, sorting by modification date does the same thing without a shell, which is the single most useful column in that table.

The rollback itself is a file swap, with one rule: do not delete, disable. Make a mods.disabled folder next to mods and move files into it rather than removing them, so that a wrong guess costs a drag rather than a download. The jar you are putting back comes from your own archive if you keep one, and from the mod's release history if you do not - every major distribution platform keeps old files, and the version number in the filename is usually enough to identify the right one.

For Factorio the mechanics are slightly different and worth knowing, because a save records the mods and versions it was made with and will refuse to load with the wrong set. Downgrading is a matter of putting the correct name_version.zip back in mods/ and checking mod-list.json:

{  "mods": [    { "name": "base", "enabled": true },    { "name": "even-distribution", "enabled": true },    { "name": "squeak-through", "enabled": false }  ]}

For Steam-delivered content, pinning is done at the SteamCMD level with a beta branch rather than in a folder:

$ steamcmd +login anonymous +app_update 380870 -beta <branch> validate +quit

380870 there is the Project Zomboid dedicated server; substitute your own game's app id. Branch names are entirely per game, many games publish none at all, and the list changes, so check the game's own documentation rather than guessing a name. SteamCMD explained covers app ids and branches properly.

When the update touched the save#

This is the case that turns a ten-minute fix into an evening, and it is worth recognising early. Some mod updates change the data written into the world: new block or item IDs, a new NBT structure, a migrated database table. Once the world has been loaded and saved by the new version, putting the old mod back does not undo it. The old version then either refuses to load the world, or loads it and quietly deletes everything it does not recognise.

Signs you are in this case rather than the simple one:

• The server started successfully at least once with the new version before things went wrong.
• The failure is missing blocks, missing items or corrupted chunks rather than a crash on load.
• The mod's changelog mentions a migration, a data fixer or a world format change.

If so, stop treating it as a rollback and treat it as a restore. Take the backup from before the update, restore it, and put the old mods back at the same time so the two match. This is the moment your backup policy is either adequate or a story you tell afterwards - backups that actually restore exists because the two look identical until you try. On RE:NODE, backup slots come with every plan, a restore is one button, and a backup can be locked against rotation, which is exactly what to do with the one you take before an update.

Bisecting a conflict nobody can read#

Sometimes the crash names nothing useful: a mixin conflict, a stack trace entirely inside the game, or a server that starts and then dies four minutes later. When reading fails, bisect. With 40 mods, binary search finds the culprit in six restarts rather than forty.

1. Copy the whole mods folder somewhere safe.
2. Move half of them into mods.disabled. Start. If the game needs a core library or API mod to run at all, keep that half in both runs.
3. If it still breaks, the culprit is in the half that is left. If it works, the culprit is in the half you removed.
4. Halve the suspect group again. Repeat.
5. When you are down to one, confirm by putting everything back and removing only that mod.

Two refinements make this less painful. Start with the mods whose timestamps changed, because the answer is usually in that group and you may finish in one restart. And if the server dies some minutes after start rather than during loading, the cause is probably a gameplay tick rather than loading, so test by standing in the area where it happens rather than by waiting.

A conflict between two current versions of two mods is the one case where rolling back is only a stopgap. Report it to both authors with the crash report attached, run without one of them in the meantime, and check back in a fortnight. Keeping a modded server clean covers deciding which mods are worth carrying at all.

Stopping it happening again#

Pin versions rather than tracking latest, and keep the last known-good copy of each mod in a folder next to the live one. Convenience that can end your evening is not convenience. Concretely:

• Keep a `mods.backup` folder containing the exact set that is currently working, and refresh it after every successful update. It costs disk and nothing else.
• Write down the working set. The start-up log already contains it; extract it to a text file in the server directory after each good update. Comparing two of those files is how you answer "what changed" in five seconds.
• Turn off automatic updates where the game lets you, and where it does not - Steam Workshop content, mostly - treat the update as a scheduled event rather than a surprise. Do it at a time you can watch it.
• Have an update window. A fixed evening, backup taken and locked first, nobody else connected, and a rule that you do not update the day a game patch lands. Mod authors need a week.
• Test on a copy. A small second server running the same versions is the only place an upgrade can fail with no audience. Staging and production on one account covers the cheap version of this, and it is more affordable for game servers than people assume.
• Update one thing at a time. Six mods updated together means six suspects and a bisect. Two at a time is slower and almost never costs you an evening.

None of this requires a host to support anything unusual. On RE:NODE mods and plugins are uploaded by you through the file manager or SFTP, or come via the game's own workshop support, and there is no whitelist of allowed mods - so the version you keep is the version you run. The console shows unfiltered live output, which is where you will read the start-up banner, and the file manager shows modification timestamps, which is how you identify the file that changed. Reading the console covers the rest of what those lines mean.

FAQ#

How do I find which mod broke my server?

Check modification timestamps in the mods folder first, because the newest file is the suspect roughly nine times in ten. If that is inconclusive, read the crash report from the top and find the first package name that is not the game or the loader. If that is also inconclusive, bisect by disabling half the mods at a time.

Can I just roll back the mod and carry on?

Usually yes, provided the server had not already written world data in the new format. If it started successfully with the new version and people played, check the mod's changelog for a migration before downgrading, and restore from the pre-update backup instead if there was one.

Why did my server update a mod on its own?

Steam Workshop content is fetched on start, so any workshop mod can change between restarts without you doing anything. Some launchers and modpack tools also track the latest release by default. Pin versions where the game allows it, and assume a restart is an opportunity for third-party content to change.

Should I update mods on the day the game updates?

No. Mod authors need days to a couple of weeks after a game patch, and updating both at once means you cannot tell which broke things. Turn off automatic game updates on a modded server, wait until the mods you depend on have released a compatible build, then move everything in one planned window.

The crash report names a mod that I am sure is fine. Now what?

That is common. A mod crashes because a library it depends on changed underneath it, so the name in the trace is the victim rather than the cause. Look at what else updated at the same time, especially anything described as an API, a core or a library, and check the version the named mod says it requires.

Do I need a backup if I keep copies of the old jars?

Yes, they solve different problems. Old jars fix a mod that will not load. A backup fixes a world that has been changed by a mod that did load. The second one is the expensive failure, and it is the one that shows up hours later rather than immediately.