Mods and modpacks on a Minecraft server (Fabric, Forge, NeoForge)

Mods change the game itself: they add blocks, items, mobs, dimensions or entire game systems. Unlike plugins, players usually need them too. This guide shows how to install mods on the server, how to get a ready-made modpack running and how to fix the most common errors.

How mods work#

Mods are loaded into the game by a loader: Fabric, Forge or NeoForge. Every mod is written for a specific loader and a specific Minecraft version. A Fabric mod doesn't work on NeoForge, and a mod for 1.21.1 usually doesn't work on 26.1. Some mods publish separate files for several loaders, so always download the file for your loader and your version.

Depending on where a mod runs, there are three kinds:

Most Fabric mods need the Fabric API library. It's a separate mod that goes in the mods folder both on the server and for players. Likewise, many mods need other libraries. A mod's page always lists them as dependencies (Dependencies).

Installing a mod through the Mods tab#

1. Open My services, click your server and go to the Mods tab.
2. Click Browse. The catalog draws on Modrinth and only shows mods for your loader and Minecraft version.
3. Type a name in the “Search mods” field and click Search.
4. On the mod, click Install.
5. In the dialog, check the Required dependencies. The customer area installs them along with the mod, for example Fabric API. Only untick the ones you've already uploaded yourself.
6. Click Install and then Restart. Mods are only loaded when the server starts.

Updating, disabling and removing mods works the same way as for plugins, see Installing plugins.

Installing a mod by hand#

1. Download the mod from its page on Modrinth or CurseForge. Check that the file is for your loader and your Minecraft version (you can see both in the Software tab under Installed software).
2. Also download all the dependencies the mod's page lists as required (Required).
3. In the Files tab, open the mods folder. If it doesn't exist, start the server once without mods, or create it with the New folder button.
4. Click Upload and choose the .jar files. You can select several at once. A single file can be at most 100 MB.
5. Restart the server.

Mods uploaded by hand show up in the Mods tab with the Uploaded manually label, and the customer area doesn't track updates for them.

What players need#

To join a modded server, a player needs:

• the same Minecraft version as the server,
• the same loader, ideally in the same version as the server,
• all content mods from the server in the same versions (not the server-side mods; client-side mods are up to each player).

The easiest way is to give players the whole modpack. If the server runs a public modpack, players just install the same version of the modpack in the CurseForge app, the Modrinth App or Prism Launcher. For your own set of mods, make a list of mods with their versions, or build your own modpack in one of these apps and share it.

Modpacks#

A modpack is a ready-made set of mods with configuration. You get it onto the server by setting up the right loader and then uploading the mods and configuration. One-click modpack installation isn't available in the customer area yet; the steps below work for modpacks from both CurseForge and Modrinth.

How much RAM a modpack needs#

The most reliable guide is the modpack author's recommendation on its page. If there isn't one, use the rough table below. Add some headroom for the number of players and the size of the world.

If the server crashes because it runs out of memory, move to a bigger plan in the Change plan tab.

Step 1: Find out the Minecraft and loader versions#

You need three things: the Minecraft version, the loader and the loader version. You'll find them:

• Modrinth: on the modpack page for the specific version (Versions). Inside the .mrpack file, they're in modrinth.index.json in the dependencies section (the minecraft, fabric-loader, forge or neoforge keys).
• CurseForge: on the modpack page in the Files tab for the specific file, or in the author's instructions. The server pack often contains a loader installer whose name gives away the version.

Step 2: Prepare the server#

1. In the Console tab, stop the server with the Stop button. After a software change, the customer area only starts the server if it was running before the change. A stopped server therefore won't generate a new world without the mods (in such a world, the ores, biomes and structures from the mods would be missing near spawn).
2. In the Software tab, choose the Server type that matches the modpack's loader.
3. Pick the Minecraft version and, in the Loader version field, the same version the modpack uses.
4. Under Server files, choose Delete all and tick I agree to the Minecraft EULA.
5. Click Change software, confirm by dragging the slider and wait until the progress shows Finished. The server stays stopped.

Step 3: Get the modpack's server files#

CurseForge: authors provide the server files as a Server Pack. It's a separate file attached to a modpack version as an additional file (Additional Files). Download the server pack of the same version your players will have and unpack it on your computer. Not every modpack has a server pack. If it's missing, use the app as described for Modrinth.

Modrinth: a .mrpack file is a ZIP that doesn't contain the mods, only links to them and the configuration. You can get the server files in one of these ways:

• With the Modrinth App (easier): install the modpack in the app, open the instance folder and take the mods and config folders and the modpack's other folders from it. Remove purely client-side mods from the mods folder (on Modrinth their environment is listed as Client only).

• For advanced users, with mrpack-install: Modrinth lists this command-line tool among the ways to deploy a modpack to a server. Download it for your system from the Releases page of the mrpack-install repository (opens in a new window) and run this in the program's folder:

  mrpack-install <FILE>.mrpack --server-dir server-modpack

  • mrpack-install – a program that downloads the modpack's server files according to its list (modrinth.index.json). The downloaded file has the system in its name, for example mrpack-install-windows.exe or mrpack-install-linux. On Windows, run it in PowerShell as .\mrpack-install-windows.exe; on Linux and macOS, first make it executable with chmod +x mrpack-install-linux and run it as ./mrpack-install-linux.
  • <FILE>.mrpack – the path to the downloaded modpack, for example Downloads/muj-pack.mrpack.
  • --server-dir server-modpack – the folder the files are downloaded to. It's created automatically.

  Besides the mods and configuration, the program also downloads the server itself with the loader. Don't upload that to our server; the loader is installed by the Software tab (step 2).

Step 4: Upload the files to the server#

Upload only these parts (if the modpack has them):

• the mods folder with all the .jar files,
• the config folder,
• other folders from the modpack, for example defaultconfigs, kubejs or resourcepacks, if the author lists them as part of the server.

In the Files tab:

1. Use the New folder button to create a folder with the same name in the server's root, for example mods.
2. Open it, click Upload and select all the files from the matching folder on your computer. You can select several files at once.
3. Do the same for subfolders (for example config and the folders inside it).

Don't upload the modpack's server .jar, the libraries folder, installers or startup scripts (run.sh, run.bat, start.sh, user_jvm_args.txt). The customer area installed the loader in step 2. The user_jvm_args.txt file isn't used on our hosting: memory and startup flags are set by the Startup tab based on the plan size and the number of mods (Startup flags and memory).

Don't upload the modpack's server.properties either. The server creates the file itself with the address and port we assigned to it. If the modpack author requires custom values (for example the world type for skyblock modpacks), set them before the first start: in the Server properties tab, click Create from defaults, change the options you need and save. The world type is only used when a new world is created; after the first start it would have no effect. A custom world type added by a mod is rejected by the form as an unknown value. Write that value directly into the server.properties file in the Files tab (Edit, save with Ctrl+S).

Step 5: Start the server and join#

1. In the Console tab, click Start. The first start of a big modpack takes several minutes.
2. Wait for the line Done (…)! For help, type "help".
3. Join from the game with the same modpack in the same version.

Configuring mods#

Edit the settings in the Files tab while the server is stopped, and start the server afterwards. .toml files use the form key = value; .json files must have valid JSON syntax (commas between items, quotes around text).

Verification#

1. In the Console tab, wait until the server reaches the line Done (…)! For help, type "help". If it ends with an error instead, continue with the Troubleshooting section.
2. In the Mods tab, on the Installed sub-tab, check that the mod is enabled. Mods uploaded by hand have the Uploaded manually label.
3. Join from the game with a client that has the same loader, the same Minecraft version and the same mods. The server mustn't kick you with a list of mods.
4. In the game, check that the mod's content works (for example that you can find a new block or item in the creative inventory).

Troubleshooting#

Look for errors in the console and in the logs/latest.log file. When the server crashes, a report is created in the crash-reports folder. The most important parts of it are the Description: line and the first line starting with Caused by:.

Players get kicked with a list of mods when joining#

The player doesn't have the same mods as the server (a mod is missing, it's a different version, or they have an extra content mod the server doesn't have). The message usually names the specific mods. Get the versions in line, ideally by having players use the same version of the modpack.

Mod resolution encountered an incompatible mod set! (Fabric)#

Fabric found on startup that the mods don't fit together. Below the message is a list: a missing dependency (for example Fabric API), a loader version that's too old, or a mod for a different Minecraft version. Add or replace the mods listed. If a mod needs a newer Fabric loader, pick it in the Software tab in the Loader version field.

Attempted to load class … for invalid dist DEDICATED_SERVER (Forge, NeoForge) or Cannot load class … in environment type SERVER (Fabric)#

The server has a client-side mod. Its name is usually in the output above the message. Remove it from the mods folder.

UnsupportedClassVersionError#

The mod needs a newer Java, so it's made for a newer Minecraft version than the server runs. Download the mod version for your Minecraft version.

The server crashes with OutOfMemoryError, or shuts down on its own without an error#

The server doesn't have enough memory. If it shuts down without an error and the Console shows Out of memory: true, it went over the plan's memory limit. In the Startup tab, check the warnings next to the startup flags and click Use recommended if needed. Removing heavy mods, lowering the view distance or moving to a bigger plan also helps. Details are in the article Performance and optimization.

Mods don't load after switching from Paper#

In the Software tab, check that the server type is Fabric, Forge or NeoForge. Mods have to be in the mods folder, not plugins.

The file is larger than 100 MB#

The file can't be uploaded through the customer area. Contact support for SFTP access.

Other messages are covered in the article Common Minecraft server errors. If you're stuck, send us the file from crash-reports or logs/latest.log.

Further reading#

• Fabric: installing mods (opens in a new window)
• NeoForge: server (opens in a new window)
• Modrinth: modpacks on a server (opens in a new window)
• Modrinth: the .mrpack format (opens in a new window)
• mrpack-install (opens in a new window)