// crash guide

Minecraft server crash: client-only mod on the server

A mod that only works in the game client, the part of Minecraft with a screen, graphics and sound, is in your server's mods folder. The server can't run client code, so it stops, usually at startup. The fix is to find that mod and take it off the server.

Updated October 2026  ·  Forge, NeoForge, Fabric, Quilt

What the error looks like

It usually happens during startup, before the server prints Done. A buggy mod can also crash a running server the same way, for example when a player joins. Check logs/latest.log and the newest file in crash-reports/, named like crash-2026-10-04_14.22.10-server.txt (Forge mod loading failures end in -fml.txt). On a Pelican panel, the live console shows the same lines and the file manager opens both folders.

Forge and NeoForge

java.lang.RuntimeException: Attempted to load class net/minecraft/client/Minecraft for invalid dist DEDICATED_SERVER

Or the class is missing outright:

java.lang.NoClassDefFoundError: net/minecraft/client/Minecraft
Caused by: java.lang.ClassNotFoundException: net.minecraft.client.Minecraft

NeoForge for 1.21.8 and newer no longer has the check that prints “invalid dist”, so there you'll only see this NoClassDefFoundError form.

The class name changes from crash to crash. It might be net/minecraft/client/gui/screens/Screen or one of the mod's own classes. Anything under net/minecraft/client is client code. In the crash report, the failing mod usually gets its own section that names the jar:

-- MOD examplemod --
Details:
    Mod File: /home/container/mods/examplemod-1.0.0.jar
    Failure message: Example Mod (examplemod) has failed to load correctly
        java.lang.RuntimeException: Attempted to load class net/minecraft/client/Minecraft for invalid dist DEDICATED_SERVER

On Forge 1.12.2 and older, the same problem says for invalid side SERVER instead.

Fabric and Quilt

java.lang.RuntimeException: Could not execute entrypoint stage 'main' due to errors, provided by 'examplemod'!
Caused by: java.lang.RuntimeException: Cannot load class com.example.examplemod.client.ExampleScreen in environment type SERVER

Or:

Caused by: java.lang.NoClassDefFoundError: net/minecraft/class_310

On 1.21.11 and older, Fabric servers use numbered "intermediary" names for Minecraft classes, so the class name won't say "client". net.minecraft.class_310 is the game client class itself. From 26.1 on, Minecraft isn't obfuscated, so the error names the class directly, like net/minecraft/client/Minecraft.

A warning that is not the crash

Forge and NeoForge logs often contain lines like this even on healthy servers:

[main/WARN] [mixin/]: Error loading class: net/minecraft/client/gui/screens/Screen (java.lang.RuntimeException: Attempted to load class net/minecraft/client/gui/screens/Screen for invalid dist DEDICATED_SERVER)

That's Mixin looking up a client class for a mod, finding it isn't available on a server, and moving on. It is a warning, not an error. If the server still reaches Done, ignore it. If the server crashes, the real cause is a different error further down the log.

Seeing in environment type CLIENT or for invalid dist CLIENT instead? That's the reverse: a mod tried to load server-only code inside a player's game. It's fixed on that player's PC, not the server: remove the server-only mod from their mods folder, or update the mod.

What it means

Minecraft comes as two programs. The client draws the world, plays sound and reads your keyboard. The dedicated server only runs the world. It has no screen, so client code isn't available there.

Mods come in three kinds: client-only, server-only, and both sides. Client-only mods change how the game looks or feels for one player: shaders, rendering, HUDs, minimaps, menus, tooltips, sounds, zoom. When one is loaded on a server, it reaches for client code the server can't load, and the server stops.

It usually gets there one of two ways:

• The server was built by copying a client's mods folder, or from the client download of a modpack.
• A mod meant for both sides has a bug and calls client code from its shared code. That's the mod's fault, not yours, and an update usually fixes it.

Fabric Loader skips any mod whose fabric.mod.json says "environment": "client", so a correctly tagged client mod won't crash a Fabric server. Fabric crashes come from mods tagged for both sides ("*", the default) that still touch client code. Forge has a similar switch: a mod that sets clientSideOnly=true in its mods.toml is skipped on a dedicated server (Forge 1.20.4 from build 49.0.6, newer Minecraft versions, and Forge 1.20.1 from build 47.3.25). NeoForge has no such switch. Mods that don't use it have to stay quiet on a server by themselves. Some do and some don't.

Common in these packs: FTB Skies 2 (FTB's file list marks 30 of its 436 mods as client-only), FTB StoneBlock 4 (26 of 414) and Create: Astral, whose server pack leaves out client mods like Sodium Extra. Build a server from a player's copy of any of them and those mods come along.

How to fix it

1. Stop the server and take a backup. On a Pelican panel, that's the Backups tab. Client-only mods don't add blocks or items, so removing them won't change your world, but a backup costs nothing.
2. Find the mod. Read the error from the top down.
   • If the class belongs to a mod (like com/author/somemod/client/...), the package name tells you which mod.
   • If it's a Minecraft class (net/minecraft/client/... or net.minecraft.class_310), read the at lines under it. Skip the ones from Java, Minecraft, the loader and Mixin (java., jdk., net.minecraft., com.mojang., net.minecraftforge., net.neoforged., cpw.mods., net.fabricmc., org.quiltmc., org.spongepowered.). The first line left is usually the mod.
   • Forge and NeoForge: the Mod File line in the crash report gives the exact jar.
   • Fabric and Quilt: provided by 'modid' gives the mod ID.
   • Still can't tell? Move half of the suspect mods out, start the server, and keep halving until the crash stops. Move a mod's required libraries with it, or you'll get missing dependency errors instead.
3. Move it out of mods/. Don't delete it. Make a folder in the server root, like mods-disabled/, and move the jar there with the panel's file manager or over SFTP. Keep it outside mods/ so no loader picks it up by accident.
4. Clear out the rest in one pass. There's often more than one, and each start only shows you the first. Common client-only mods: OptiFine; shader and rendering mods like Oculus, Iris, Sodium, Embeddium and Rubidium; most minimaps and world maps; HUD, tooltip, menu and loading-screen mods; sound, zoom and cosmetic mods. Modrinth pages say whether a mod runs on the client, the server or both. Or paste your whole mods folder into the client-or-server-side checker. On CurseForge, check the description. Don't pull a mod just because it shows something on screen: JEI and JourneyMap, for example, are built to run on both sides. If a mod adds blocks, items, mobs or dimensions, it is not client-only. Leave it in.
5. Better yet, start from the server pack. Many CurseForge modpacks publish a server pack for each release, listed on the pack's Files page. Modrinth packs (.mrpack) mark every file as client, server or both, and server installers use that to leave client files out. Use the server pack for the exact pack version your players run. Any jar in your client folder that isn't in the server pack is probably client-only. If the pack has no server pack at all, here's how to build one.
6. If a both-sides mod is to blame, update it. When the error points at a mod that adds content, that mod is calling client code where it shouldn't. Update it to the latest build for your Minecraft version and loader, check its issue tracker, or roll back to the last version that worked. Don't remove a content mod from a world that uses it.

How to check it's fixed

• Start the server and watch the console. It should reach Done (12.345s)! For help, type "help", with no new file in crash-reports/.
• Search logs/latest.log for invalid dist, invalid side and environment type (on NeoForge for 1.21.8 and newer, net/minecraft/client). Any hits left should be the harmless [mixin/] warnings above, not errors.
• If a different error shows up now, that's progress: the loader got further. If you moved a library by mistake, you'll get a missing dependency error that names it. Move that one back.
• Join with the full client pack. Players keep their shaders, minimaps and other client mods on their own PCs. Only the server's folder changed.

Related crash guides

• Missing mod dependency — "requires mod" and "Missing or unsupported mandatory dependencies"
• Wrong mod loader or Minecraft version — a Fabric mod on Forge, or a mod built for another version
• Mixin errors — "Mixin apply failed" and "InvalidInjectionException"
• Duplicate mods — "Found duplicate mods" and "DuplicateModsFoundException"
• Friends can't join — "mismatched mod channel list" and other join errors, once the server is up
• Modpack with no server pack — build the server files yourself and leave the client-only mods out