Client-only mods on a server: why they crash it
Optimisation and interface mods often exist only on the client. Put one on a server and it crashes at boot with a class-not-found error. Here is how to spot them.
The short version
Client-only mods crash a server on startup because they reference rendering classes that only exist in the client jar. The crash usually names a class under net.minecraft.client or throws NoClassDefFoundError. Remove the mod from the server; players keep it installed locally and everything works.
This is the single most common way a working modded setup breaks when someone moves it to a server. The mod list ran perfectly in singleplayer, gets copied to /data/mods, and the server refuses to start.
#Why it happens
Minecraft ships as two different jars. The client jar contains everything the server jar does, plus all the rendering: screens, textures, shaders, particle systems, the lot.
A client-only mod is written against those rendering classes. On a server they simply do not exist, so the moment the loader initialises the mod it asks for a class that is not there and the JVM gives up.
The crash usually looks like one of these:
java.lang.NoClassDefFoundError: net/minecraft/client/renderer/GameRenderer
java.lang.ClassNotFoundException: net.minecraft.client.gui.screens.Screen
java.lang.RuntimeException: Attempted to load class net/minecraft/client/... for invalid dist DEDICATED_SERVER
That last one is Forge and NeoForge being explicit about it, which is helpful of them. Any mention of net.minecraft.client or invalid dist in a server crash means a client mod is present.
#Which mods are client-only
The reliable check is the mod page: CurseForge and Modrinth both publish an environment field showing client, server or both. Look before you upload.
Failing that, the rule of thumb is what the mod changes:
| The mod changes | Where it goes |
|---|---|
| What you see: shaders, minimaps, HUD, animations, tooltips, sounds | Client only |
| What exists: blocks, items, mobs, dimensions, recipes, world generation | Server and client |
| What happens: game rules, economy, protection, moderation | Server only |
Common client-only mods people put on servers by accident: Sodium, Iris, OptiFine, Xaero's Minimap, JourneyMap in its client build, Mouse Tweaks, Better F3, Zoomify, and most resource-pack-adjacent mods.
Common source of confusion: Sodium is client-only, Lithium is server-side. They are by the same team, the names are similar, and one of them will crash your server. Lithium is the one that helps it.
#Fixing it
- Read the crash for the class name. Anything containing
net.minecraft.clientis your signal. - Find which mod owns it. If the class name does not make the mod obvious, remove the mods you most recently added first.
- Delete it from
/data/modsand restart. - Tell your players to keep it. Their client is where it was always meant to live.
If several client mods are present, the server crashes on the first one it reaches and says nothing about the rest. Expect to repeat this once or twice.
#The mods that go on both
Some mods ship one jar containing both sides, and it belongs in both places. JEI, REI and most content mods work this way, and running them on the server but not the client (or the reverse) produces a mod-mismatch disconnect rather than a crash.
If a mod is listed as required on both sides, both sides means both. The server having it is not enough.
#Doing this properly from the start
If you are assembling a mod list for a server rather than fixing one, split it in two before you upload anything: a server list and a client list. Most mods go in both, performance and visual mods go in the client list only, and admin tooling goes in the server list only.
Ten minutes of sorting up front removes an entire evening of crash-and-remove later, which is not a trade most people make until the second time.
#Frequently asked questions
How do I know if a Minecraft mod is client-only?
Check the mod page: CurseForge and Modrinth both label environment as client, server or both. As a rule, anything that changes what you see (shaders, minimaps, HUD tweaks, animation and rendering mods) is client-only. Anything that changes what happens (world generation, mobs, blocks, recipes) needs to be on the server.
What error does a client-only mod cause on a server?
Usually NoClassDefFoundError or ClassNotFoundException naming a class under net.minecraft.client, or a crash mentioning rendering, screens or textures during mod loading. The server jar does not contain those classes, so the mod fails the moment it tries to touch one.
Do players need to remove client-only mods too?
No, the opposite. Client-only mods are meant to be installed on the client and nowhere else. Remove it from the server, leave it in every player's mods folder, and both sides are happy.
Written and maintained by the Hostd engineering team. Last updated 2026-08-05. Notice a mistake? Tell us.