invalid dist DEDICATED_SERVER: fixing a client-only mod on a Minecraft server

Last updated 2026-09-09 · MineXHost

This crash means a mod reached for a class that only exists on a Minecraft client while running on a dedicated server. The mod loader refuses the load on purpose. The frustrating part is that the message names the class it refused, which is a Minecraft class — never the mod that asked for it.

The message, in both of its wordings

Forge and NeoForge strip client-only code out of the server at load time and throw when something asks for it anyway. The exact wording depends on how old the pack is, which matters because searching for the wrong one finds nothing.

Why the named class is never the culprit

The class in the message is the class that was refused, and it is a Minecraft client class every single time — something like net.minecraft.client.Minecraft or net.minecraft.client.gui.screens.Screen. Removing it is not an option and it is not broken. What you need is the mod that asked for it, and that is in the stack trace, not the message.

1. Scroll to the stack under the exception and read downwards past the loader frames (cpw.mods, net.minecraftforge, net.neoforged, org.spongepowered).
2. The first package that is none of those belongs to a mod — for example com.someauthor.somemod.
3. Match that package to a jar in mods/. Most mods use their own name in the package, so this is usually obvious once you know to look there.
4. If the crash says “Failed to create mod instance”, the log normally names the mod id directly on that line. Take it.

Two corpora matter here and they are not the same file. The console you see in the panel is stdout and stderr; the full construction stack and the RuntimeDistCleaner frames often appear only in crash-reports/*.txt. If the console tail is thin, read the crash report.

The mods this happens to

Almost every case is a client-side mod that ended up in a server's mods folder because the pack was installed from its client zip. The families that show up repeatedly:

• Rendering and performance mods that bind native graphics libraries — a NoClassDefFoundError naming org/lwjgl alongside a named render mod is this crash wearing a different hat.
• Shader and lighting mods, which exist entirely to change how the game draws.
• Cosmetic loaders and account overlays, whose stub loaders install themselves before the mod list is even read.
• Minimaps, HUD mods, inventory tweaks and anything whose whole feature is a screen.

How to fix it

1. Back up the world folder.
2. Move the mod the stack named out of mods/ and restart. Client-only mods do not need a server copy — keep it in your own client mods folder and it still works in multiplayer.
3. Expect more than one. Client packs routinely ship a dozen client-only mods, and the server surfaces them a few at a time as each boot gets further than the last.
4. Where the pack publishes a server pack, use it. That is the same pack with the client-only mods already removed, and it saves the whole exercise.
5. Check the mod's page before removing it permanently: a mod tagged Client-side only on Modrinth, or Client on CurseForge, is meant to be absent from the server.

The awkward case: a server mod that requires a client mod

Sometimes the client-only mod cannot simply be removed, because another mod in the pack declares it as a required dependency. Remove it and the loader refuses to start over a missing dependency; keep it and the dist check kills the server. The pack is not bootable on a dedicated server as shipped.

The real fix is to remove the requiring mod as well, if you can live without it, or to use the pack's server pack where one exists. If neither is acceptable, this is a pack bug worth reporting to its author — it is not something a host can configure around.

What MineXHost's launcher does with this crash

MineXEngine recognises both wordings, the construction-time variant and the transformer variant, and reads the stack rather than the message to attribute the mod. Where the class in the message is obfuscated it drops the attribution rather than guessing — an obfuscated Minecraft class genuinely does not identify a mod, and a guess there removes the wrong file.

Before your server's first boot, mods that declare themselves client-only in their own metadata are moved out of mods/ during install, which is why most client packs boot here without a hand-edit. Mods that do not declare it — and plenty do not — still surface at runtime, and there the engine identifies rather than deletes: crash recovery on a customer server names the file and leaves your mods folder alone.

For the dependency deadlock above, the engine detects that the pack cannot boot as shipped and writes a proposal naming every file that would have to go, with the evidence for each. The panel shows you that list and applies nothing until you approve it.