Upload a mod to your modded Minecraft server
Stop the server, drop your mod JAR into the mods folder with every dependency it needs, then start it back up — the right way to add Forge or NeoForge mods without a crash on boot.
Step 2 of 2 · minecraft-server-extensions
Minecraft mods (Forge, NeoForge, Fabric) live in a mods/ folder next to server.jar. They are not the same thing as Paper plugins — mods extend the game itself with new blocks, items, mechanics, and recipes, so the client and server have to agree on exactly which mods are loaded. Two rules make modded uploads boring instead of painful: stop the server before you touch the mods folder, and never upload a mod without also uploading every dependency it lists. Skip either and the next boot ends in a stack trace.
01 Stop the server first
Open your modded server from the dashboard. The state badge top-left should read RUNNING (green dot). Click STOP in the power buttons — not RESTART. NeoForge and Forge crash hard when a mod appears or disappears in mods/ while the JVM is alive, because they cache the mod list at startup and re-scanning mid-flight tears the classloader apart. Wait until the badge switches to OFFLINE before you go any further; this usually takes 5–15 seconds depending on how much state the modpack has to save. KILL is the panic button — it sends SIGKILL rather than asking the JVM to shut down — use it only if STOP hangs for more than a minute.
02 Open the mods folder
Switch to FILES, then click into the mods folder. What's already there is the modpack's pinned mod set — for the Create Aeronautics pack above, that's the three JARs the install script downloaded on first boot. Leave the existing mods alone. Every one of them is either a dependency something else needs, or part of the modpack's curated bundle. Adding a new mod here means dropping a JAR next to the existing ones — not replacing them.
If you don't see the mods/ folder at all, your server is running vanilla Paper or Bedrock, not a modded Forge/NeoForge/Fabric build. Mods and plugins are separate worlds — see the plugin upload guide for Paper.
03 Upload your mod JAR (and its dependencies)
Click ↑ UPLOAD in the toolbar. The target is locked to /mods — the breadcrumb does that for you. Pick your mod's .jar file and click UPLOAD →. The file lands in mods/ within a few seconds.
Now the dependency rule. Mods usually depend on other mods — a Create addon depends on Create, an Applied Energistics machine depends on AE2, and almost everything depends on a logging or library mod like Cloth Config or Architectury. CurseForge and Modrinth list these on every mod page. Upload every required dependency for exactly the Minecraft + loader version your server is running (the modpack version chip on the OVERVIEW → SERVER OPTIONS panel tells you which one). Forge mods and Fabric mods are not interchangeable — a Fabric JAR on a NeoForge server simply won't load and produces a confusing "missing entrypoint" line in the console.
Once your mod and its dependencies are all sitting in mods/, switch back to OVERVIEW and click START. The server takes longer than a vanilla restart because NeoForge has to scan and link every mod — for a 60-mod modpack, give it two minutes. The console prints Loading X mods: … as it goes, then Done (X.YZs)! once the world is up.
Troubleshooting
- "The server crashes on startup after I added a mod." Almost always missing or mismatched dependencies. Scroll the console to the first red
ERRORorFATALline — Forge/NeoForge spells out which mod ID is required but missing, and which version of which loader expected. Re-upload the dependency at the correct version. If the stack trace mentionsMissingModsExceptionorModLoadingException, it's a dependency. If it mentionsClassNotFoundExceptionon a recognisable class name (e.g.io.netty…), the mod was built for a different Minecraft version. - "It says my mod is for a different Minecraft version." The console line is something like
Mod XYZ requires minecraft 1.20.1 but found 1.21.1. Stop the server, delete the wrong-version JAR via the file manager (right-click → DELETE), upload the correct one, and start again. Don't keep a wrong-version mod sitting inmods/"for later" — Forge tries to load it anyway and will keep crashing. - "I want to add multiple mods at once." Two options. (a) Repeat the upload three or four times — fine for half a dozen mods. (b) Zip the mod JARs into a single archive, upload that archive, and tick Extract after upload (.zip / .tar.gz) in the upload dialog. The dashboard unpacks it directly into
mods/. Make sure the archive contains the JARs at its root — not nested in a subdirectory — or you'll end up withmods/myzip/mod-1.jarinstead ofmods/mod-1.jar, and the loader won't find anything. - "The mod won't load and there's no obvious error." Forge and NeoForge are chattier than they look — open the CONSOLE on the Overview tab and scroll back. Anything tagged
WARNis suspicious for a missing optional dependency; anythingERRORis fatal. If you've changed mods and the launcher just hangs atLoading X modsfor more than 3 minutes, kill and start again — sometimes a corrupted JAR (incomplete upload) needs a fresh download to fix. - "I want to roll back the whole thing." Switch to the BACKUPS tab and restore the snapshot from before you started uploading. Your tier ships with at least 2 backup slots, and a fresh one is taken automatically every night — so as long as you upload during the day, the previous night's snapshot is your safety net.
- "Where do I find mods that won't break things?" // TODO: link the operator's preferred mod sources here (Modrinth, CurseForge, modpack authors' own download pages) once we have an opinionated short list. Pin to the same Minecraft + loader version your modpack uses — a 1.21.1/NeoForge server only accepts 1.21.1/NeoForge mods.