On this page
Mods change the game itself: new blocks, mobs, machines, dimensions, or faster world generation. Unlike plugins, many of them also have to be installed by every player. They run on Fabric, NeoForge and Forge servers; on Paper, Purpur or Spigot you use plugins instead, which the plugins guide covers.
If you want a ready-made set of mods that already work together, a modpack is easier; see installing a modpack. This guide is for picking your own mods with the Mod Manager.
Know your loader and version
A mod file is built for one loader and usually one Minecraft version, and it only loads when both match your server. Before installing anything, write down:
- The loader: the type you created the server with, Fabric, NeoForge or Forge. Our NeoForge server installs Minecraft 1.21.1 and our Forge server installs 1.20.1.
- The Minecraft version: the first lines of the console when the server starts show the loader and the game version.
The rules that trip people up:
- Fabric mods do not load on NeoForge or Forge, and NeoForge or Forge mods do not load on Fabric.
- NeoForge and Forge split apart after Minecraft 1.20.1. On 1.21.1, a mod made only for Forge does not run on NeoForge, and the other way round.
- Minor versions matter. A mod built for 1.21 is not guaranteed to work on 1.21.1; trust the versions the mod's page lists.
Getting these two facts right first saves most of the debugging later.
Install a mod from the panel
- Open your server in the panel. In the sidebar, open the Minecraft group and click Mod Manager.
- In the Filters box, leave Provider on Modrinth. CurseForge appears in the list too, but it is not set up on Torchlite.
- Set Minecraft Version to your server's version and Mod Loader to your loader. Both only narrow the search results.
- Search for the mod and click it. Mods that Modrinth marks as unusable on a server are left out of the results.
- Choose the file under Select Version (see below) and click Install Mod.
The panel downloads the .jar into the mods folder and confirms that the installation started. Press Restart in the console to load it. Restarting a running server keeps its slot, while Stop and then Start can land you in the start queue when the node is full.
Choose the right file
Select Version lists every file the mod has ever published, for every loader and every Minecraft version, and preselects the first one. That first file may be for a different loader or a newer game version than yours.
Mod authors often put the loader and game version in the file name, but not always. The reliable way is to open the mod on modrinth.com, go to its Versions tab, filter by your loader and game version, and note the name of the newest matching file. Then pick exactly that name in the panel.
Dependencies
The Mod Manager installs one file. It does not fetch the other mods that file needs, so you add them yourself the same way.
On Fabric, nearly every mod needs Fabric API, which Fabric Loader does not include. Install it first on any Fabric server. Other libraries that come up often are Cloth Config, Architectury API, GeckoLib, Fabric Language Kotlin and Kotlin for Forge. A library does nothing on its own; it is shared code that other mods build on.
Each file's page on Modrinth lists its dependencies and marks them required or optional. If you miss one, the server tells you at startup: it stops and names the missing mod and the version it expected. Install that and restart.
Server-side and client-side mods
Every mod runs on the server, on the player's game, or on both. That decides where it has to be installed:
| Kind of mod | On the server | Players need it |
| Adds blocks, items, mobs, biomes, dimensions or machines, like Create or Farmer's Delight | Yes | Yes, same version |
| Server tools and performance, like Lithium, FerriteCore, Chunky, spark or LuckPerms | Yes | No |
| Visuals and client performance, like Sodium, Iris or Mod Menu | No | Their own choice |
| Libraries, like Fabric API or GeckoLib | When a server mod needs it | When one of their mods needs it |
Modrinth's page for each mod shows whether it runs on the client, the server or both. Content mods are the ones that must match exactly: if the server has a block the player's game does not know about, the player cannot join.
Client-only mods do not belong on the server. Fabric usually just skips them, but on NeoForge and Forge they often crash the server at startup. Players who want them install them in their own game.
Tell players what to install
Players need the same loader and the same Minecraft version as the server, plus every mod from the first row of the table, in the same versions. The simplest way to share that is a list of mod names and file versions, or a small modpack you build in a launcher such as the Modrinth App or Prism Launcher and send to friends.
Server-only mods such as Chunky or spark stay off that list. Keep it updated whenever you add or update a content mod, because a mismatch is the most common reason players are kicked when they join.
Update or remove a mod
To update, install the new file, then delete the old one from Files → mods. Installing does not replace the old file, and two copies of the same mod stop the server.
To remove a mod, stop the server, delete its jar from mods, and start again. Its settings stay in the config folder until you delete them. Be careful with content mods: when one is removed, its blocks and items disappear from the world. Make a backup in Backups before you remove one from a world you care about.
Common problems
The server stops and lists missing dependencies
A mod needs another mod that is not installed. The message names the mod ID and the version range it expects. Install that dependency, in a version for your loader and game version, and restart.
"Attempted to load class … for invalid dist DEDICATED_SERVER"
A client-only mod is in mods on a NeoForge or Forge server. The lines around the error usually name the mod. Delete it; players can keep it in their own game.
The server complains about duplicate or incompatible mods
Two versions of one mod are in mods, or a file is for the wrong loader or game version. Check the file names, keep one copy built for your setup, and restart.
Players are kicked with a list of mods
Their mods or mod versions do not match the server. Compare their list with yours, especially content mods, and have them install the exact same files.
The server runs out of memory
Each mod costs memory. Remove the heavy ones, or for a big NeoForge or Forge setup use the Max plan, which for Minecraft is only offered on those two types.
Stuck on a step?
Ask on the forum. Your question links back to this guide, so whoever answers knows where you are.
About the author
Torchlite team
The people who run Torchlite
We build and run the Torchlite panel and the nodes. Every guide is checked on our own servers before it goes up, and updated when the panel changes.
