Add mods to a Minecraft Forge server

1. Pick the right file#

Mod sites list each release separately. Modrinth's API describes a version's loaders as "The mod loaders that this version supports", next to its game_versions, and CurseForge says its Versions section "lists the mod/modpack's versions, and the modloader that each version/file is compatible with." Read those two tags on the file you download, not the project's summary, which covers every release at once.

Forge, not NeoForge or Fabric

NeoForge started on 13 July 2023 as "a fork of MinecraftForge", and the two loaders have drifted apart since. From Minecraft 1.20.5, NeoForge says "the only recognized metadata file for mods is neoforge.mods.toml", while Forge still reads META-INF/mods.toml. CurseForge lists them as separate loaders, and many mods ship a build for each.

The wrong build fails quietly. In our test we put the NeoForge build of Waystones into the Forge server's mods folder, and then a Fabric API jar. Forge ignored both without a single line in latest.log; the server started as if they were not there. Because the world had already used Waystones, the log carried this instead:

The following mods have version differences that were not resolved:
waystones (version 21.1.46 -> MISSING)
Things may not work well.

followed by Unidentified mapping from registry minecraft:block and a list of every Waystones block. If a mod you added never shows up, check its loader first.

Your exact Minecraft version

A Forge mod names the Minecraft versions it supports, and Forge checks the range when the server starts. We added the Waystones build made for Minecraft 1.20.1, and the server stopped before loading the world with:

Mod waystones requires minecraft 1.20 or above, and below 1.21
Currently, minecraft is 1.21.1

The fix is the release built for your version. A release marked only "1.21" can still be right: Forge 1.21.1 treats Minecraft 1.21 as compatible when it checks a mod's range.

Server, client or both

Some mods only change the game on the player's screen, such as menus, minimaps and inventory tweaks. A mod can declare clientSideOnly=true, and Forge then skips it on a dedicated server. In our test, Mouse Tweaks declared exactly that, and the server logged:

returned 1 files which are client-side-only mods, but we're on a dedicated server. They will be skipped!

A client-only mod that does not declare itself is riskier. If it loads client code on the server, it can stop the server; one form of that error in Forge's loader source is Attempted to load class ... for invalid dist DEDICATED_SERVER. Modrinth marks which side a project needs (its older client_side and server_side fields are being replaced by an environment field); keep client-only mods off the server.

2. Bring every dependency#

Many mods need a library mod beside them, and Forge refuses to start without it. Waystones needs Balm. With Waystones alone in the folder, our server stopped with:

Mod waystones requires balm 21.0.39 or above
Currently, balm is not installed

That message names the missing mod and the lowest version it accepts. Download that mod, for Forge and for the same Minecraft version, and put it beside the first one; with Balm added, the server started and listed both mods. When a start fails like this, Forge also writes a report to crash-reports/crash-<date>-fml.txt. An optional dependency can be left out, but if it is present in the wrong version Forge still refuses to load.

3. Install, start, read the log#

1. Stop the server. Forge finds its mods once, when it starts, so a jar added to a running server does nothing until the next start.
2. Put the .jar straight into the mods folder. Forge only reads jar files directly inside mods; a jar in a subfolder is ignored. A subfolder is also a way to switch a mod off without deleting it (we moved ours into mods/disabled-1.21.1 and the server started without them), but only for mods that add nothing to the world (no blocks, items, mobs, biomes or enchantments): a world that used a switched-off mod loses that mod's entries, as section 4 shows.
3. Keep one copy of each mod. When two jars of the same mod are present, Forge quietly keeps the newest and says so only in logs/debug.log, so delete the old jar when you update.
4. Start the server and read logs/latest.log from the top. The first error is the one to fix; everything after it is usually a consequence.

Where the mod's settings go

Forge has three kinds of config. COMMON configs live in the server's config folder; SERVER configs live inside the world, in world/serverconfig, and Forge's docs mark them as synced to clients. CLIENT configs never reach the server. On our server, Waystones wrote config/waystones-common.toml on its first start, and Forge's own forge-server.toml appeared in world/serverconfig. A file put in defaultconfigs is copied in only when a config file does not exist yet, which is the way to preset values for a new world.

4. What your players need#

Players need the same Minecraft version, Forge, and every mod on the server that is not server-only, in the same versions. A Forge server advertises its mod list in the server-list ping, so the multiplayer screen can mark it compatible or not before anyone joins; our test server's answer listed waystones 21.1.46 and balm 21.0.66. When the lists still differ at join time, Forge's client shows a screen headed "Your client is missing the following mods, install these mods to join this server:" or "The following mod versions do not match, install the same version of these mods that the server has to join this server:". A player without Forge is refused when the server's mods need Forge on the client, with "This server has mods that require Forge to be installed on the client."

Removing a mod is the step to treat with care. On our server, once the Forge build of Waystones was gone (the NeoForge jar we swapped in did not count), the world started without Waystones, logged the MISSING warning above, and Forge added:

Forge Mod Loader detected missing registry entries.
There are 99 missing entries in this save.
If you continue the missing entries will get removed.

Back up the world folder before you remove a mod or change its major version.

Where ForgeWorld Gaming fits#

ForgeWorld Gaming sells Forge as its own Minecraft edition, next to Paper and Vanilla, and only a Forge server loads Forge mods. A new Forge server comes with Forge installed for the Minecraft Version on its Startup tab; our test server got 1.21.1 with the recommended build, 52.1.0, and an empty mods folder. Upload mod jars into mods on the Files tab, then restart from the Console tab and watch the startup there, or open logs/latest.log on the Files tab. If a mod needs a newer Forge build than the one installed, set Build Type to latest on the Startup tab and use Reinstall Server on the Settings tab: on our server that installed 52.1.20 and kept the mods and the world in place, and the next start printed Forge mod loading, version 52.1.20, for MC 1.21.1. Take a backup first all the same, as the panel itself advises. Last checked 2026-10-20.

Prefer renting to keeping your own server machine online? ForgeWorld Gaming currently offers Minecraft Paper Standard: 8, 16, 24, 32, 40, 48, 56 player slots at CA$9.89–CA$65.99/month. Hosted in Iowa, United States. Prices are in Canadian dollars, with no setup fee and cancel any time. Your server is set up automatically after payment. Continue to secure billing, Minecraft · Paper, CA$9.89 / month (Standard, 8 slots), or compare Minecraft Paper plans.