Join our Discord and be part of our community!
Modpack Installation Troubleshooting
This guide covers common issues that may occur when installing a modpack on your Minecraft server, including crash loops, missing dependencies, and client-side mod conflicts. Follow the steps below to diagnose and resolve the most frequent modpack installation problems.
Resolve First-Startup Crashes
- It is sometimes normal for a modpack to crash on the very first startup. Many modpacks perform initial world generation tasks or load large amounts of assets, which can cause a one-time crash.
- Make sure the correct Java version is selected for the modpack:
1.17.1and earlier: Java 81.18–1.20.4: Java 171.20.5–1.21.x: Java 2126.1+: Java 25- Some modpacks specify other Java versions. For example, GT: NH recommends Java 25 for a 1.7.10 modpack. Consult the modpack's website or community for specifics.
- Read the official installation guide of each modpack. Some modpacks require specific settings on the server side, like deleting specific mods (such as client-side-only mods).
- If the server crashes on first startup, wait until the console fully stops, then start it again. Most modpacks succeed on the second attempt.
- If the server appears frozen during startup, stop the server, click the skull symbol to kill the process, and start it again.
- If the server continues to crash after multiple restart attempts, proceed to the troubleshooting steps below.
Diagnose the Crash via Console Logs
- The server console logs contain the most important clues about what is causing the crash. Open the Console tab in your panel and review the output carefully.
- To narrow down the cause, open the latest log file and search (Ctrl+F) for the following keywords:
Caused byFailed to loadCould not loadDuplicate modMissing dependencyFileNotFoundExceptionFailed to start the minecraft server
- If the log output references a specific mod name, that mod is likely the cause of the crash. Note its name before proceeding.
Remove the Problematic Mod
- If you identified a specific mod in the logs, navigate to the Files tab in your panel and open the
modsfolder.
- Locate the mod file (
.jar) matching the name from the log, and delete it. - Start the server again and monitor the console to confirm the crash is resolved.
- If the server still crashes, repeat the process, as there may be more than one problematic mod.
Identify and Remove Client-Side Only Mods
- Some modpacks include mods that run only on the client side (i.e., on the player's computer) and not on a server. These mods will cause the server to crash if left in the
modsfolder. - If you do not find an obvious error in the logs, search the mods included in your modpack online to check whether any are client-side only.
- A good starting point is to search
[mod name] client-side only server crashon Google, or check the mod's page on CurseForge or Modrinth. - Remove any confirmed client-side only mods from the
modsfolder and restart the server.
Reinstall the Modpack
- If the crash persists and you cannot identify a specific mod as the culprit, perform a clean reinstall of the modpack.
- Navigate to the Files tab and delete all existing server files, leaving the directory completely empty.
- Reinstall the modpack from the panel's modpack installer (see Install a Modpack, or Manual Installation of Modpacks for custom packs). When prompted, do not select the option to wipe the server — this ensures a clean reinstall without additional complications.
Use Binary Testing on Custom Modpacks
- If you are running a custom modpack (not from CurseForge, Modrinth, or FTB) and no obvious error is visible in the logs, binary testing is an effective method to isolate the problematic mod.
- Binary testing isolates the offending mod by removing half of the mods, testing whether the crash persists, and repeating with progressively smaller groups. Move mods to a temporary folder outside
mods/rather than deleting them, so you can restore them once the culprit is found. - Move half of the mods out of the
modsfolder. - Start the server.
- If it crashes, the problematic mod is in the remaining half. Remove half of those and repeat.
- If it does not crash, the problematic mod is in the half you removed. Add half of them back and repeat.
- Be mindful of dependency mods, since removing dependencies will cause the server to crash as well.
- This process narrows down the cause efficiently without testing each mod one by one.
Resolve Player Connection Issues
Verify Connection Basics
- A modded server can take significantly longer to start than a vanilla server, often 5 to 15 minutes, depending on the modpack's size and complexity. Wait for the console to display a
Done (XX.XXXs)! For help, type "help"message before connecting. - Verify that the connection address in the Minecraft client matches the address shown on your server's overview page in the panel (IP and port).
- Confirm that the client has installed the exact same modpack version, Minecraft version, and mod loader (Forge, Fabric, NeoForge, or Quilt) as the server. A mismatch on any of these will prevent the connection.
Identify the Connection Error
- Attempt to join the server and note the exact error message the Minecraft client displays. The wording usually points directly to the cause.
- Common error messages and their causes:
Connection refused: the server is not listening on that port. This usually means the server is still starting up, has crashed during startup, has stopped entirely, or the client is connecting to the wrong port. Confirm the Console showsDoneand verify the port matches the address on your server's overview page.Connection timed out: the address is incorrect, or a firewall or network on the client side is blocking the connection.Outdated serverorOutdated client: the Minecraft version or mod loader version on the client does not match the server.Mod rejections from serverorConnection closed - Mismatched mod channel list: the client's mod list does not match the server's mod list. (Example below)You are not whitelisted on this server: the whitelist is enabled, and your username is not on it.
Resolve Mod Mismatches
- Compare the contents of the
modsfolder on the server with the client'smodsfolder. Both must contain the same.jarfiles at the same versions. As shown in the screenshot above, the error usually lists the exact mods and versions needed. - Remove any extra mods present on the client but missing from the server.
- If you updated the modpack on the server, update the client to the same version, and vice versa.
- After making changes, Restart the server and reconnect from the client.
Resolve Whitelist Issues
- Open the Console tab in your panel and run
whitelist listto view the current whitelist. - To add a player, run
whitelist add <username>. - To disable the whitelist entirely, run
whitelist off. - Whitelist commands take effect immediately and do not require a server restart.
Verify Server Configuration
- Open the Files tab and edit
server.properties. Confirm the following values: server-ip=should be empty in most cases. A value here forces the server to bind to a specific local address and can prevent external connections.server-port=should match the port shown in your panel.max-players=must be greater than0.online-mode=truerequires players to use a paid Minecraft account. Set tofalseonly if running a cracked or offline-mode server.- Restart the server after editing
server.properties.
Contact Support
- Since modpacks and mods vary widely and can be highly complex, first seek support from the modpack's own community before opening a ticket with UltraServers. They will be far more familiar with their modpack's quirks and known issues.
- Most modpacks offer support through a Discord server, a GitHub issues page, or a dedicated forum thread.
- If the modpack's community or maintainers confirm the issue is related to hosting or server infrastructure, open a support ticket with UltraServers and include:
- A description of the issue.
- The steps you have already taken to resolve it.
- The relevant portion of the server log containing the error.
If you require further assistance, you can open a support ticket here.
Feedback and suggestions can be submitted here or further discussed on our Discord server.
- Modpack Installation Troubleshooting
- Resolve First-Startup Crashes
- Diagnose the Crash via Console Logs
- Remove the Problematic Mod
- Identify and Remove Client-Side Only Mods
- Reinstall the Modpack
- Use Binary Testing on Custom Modpacks
- Resolve Player Connection Issues
- Verify Connection Basics
- Identify the Connection Error
- Resolve Mod Mismatches
- Resolve Whitelist Issues
- Verify Server Configuration
- Contact Support