Mod & Plugin Troubleshooting Guide

While hosting your own Minecraft server with mods or plugins, you might run into some occasional issues. These include crashes, errors, invalid commands, database problems, and more. Due to all these, we’ve created this Apex Hosting guide to help you troubleshoot mod and plugin issues in Minecraft.

Before you begin, we strongly recommend creating a new backup of your world and server files. You can do that by either downloading files via FTP File Access in your Apex server panel OR using the Backups tab to make one. This way you ensure no data is lost while troubleshooting.
 

Mod Troubleshooting – Minecraft

1. Game Crashes Immediately on Startup

The Cause: This is almost always a critical initialization failure. The most common culprits are mismatched mod loaders, incompatible Java versions, or a corrupted mod file.

1. Mismatched Mod Loader: You might have downloaded Fabric mods but are running a Forge loader (or vice versa).
2. Version Incompatibility: A mod built for Minecraft 1.20.1 is being loaded on Minecraft 1.21.
3. Java Version: Old Minecraft versions require older Java (e.g., Java 8 for 1.12.2), while newer versions require Java 17 or 21.

 
How to Fix:

1. Check the Logs: Head towards your crash reports folder .minecraft/crash-reports/ or check the server’s latest.log. Look for lines stating RUN-TIME EXCEPTION or pointing to a specific mod file.
2. Match the Loader & Version: Ensure the server type (Forge/Fabric) matches the client launcher exactly.
3. Purge & Isolate: Remove all mods, then add them back in batches of 5 to isolate the exact mod causing the crash.

2. Missing Required Dependencies Error

The Cause: Many Minecraft mods are built on top of shared libraries or core frameworks (dependencies). If a mod requires Cloth Config, Architectury API, or Fabric API and it isn’t present in the mods folder – the game will refuse to launch.

How to Fix:

1. Read the Error Message: The error message usually tells you exactly what is missing and what version is required.
2. Download the Dependency: Locate the missing mod on Modrinth or CurseForge.
3. Install on Both Sides: Ensure the downloaded dependency file is placed into both the server’s mods folder and the player’s local client mods folder.

3. Connection Lost & Mod Rejections

The Cause: This error occurs when there is a mismatch between the mods installed on your computer and the mods installed on the Minecraft server. For modded servers, the server’s mods folder and the client’s mods folder must be virtually identical.

How to Fix:

1. Check Mod Lists: Verify that both the server and the client have the exact same versions of the mods. A server running Mod v1.2.0 will often reject a client running Mod v1.2.1.
2. Identify Client-Side vs. Server-Side Mods: Check the mod’s CurseForge or Modrinth page to see if it’s client, server, or both. You may also check this large list of client-side mods too.
3. Clean Sync: The easiest fix is to compress the server’s mods folder into a .zip file, then replace the local mods folder contents with it.

4. ‘Ticking World’ or ‘Ticking Entity’ Crashes

The Cause: This indicates a world corruption issue or a severe logic error caused by a specific modded entity, block, or item acting up in a loaded chunk. This usually happens mid-game rather than at startup.

How to Fix:

1. Update Mods: Outdated mods can occasionally cause ticking issues, so updating them to their latest version for your server can help resolve them. This also applies to modpacks.
2. Install Neruina: This is a mod that ‘fixes’ these ticking errors on your server. It allows you to do various actions to remove the ticking entity. Download here.
3. Restore Backup: In many cases, restoring your world to a previous version is the best fix. This way it prevents the ticking issue from happening again (not guaranteed).
4. Mod Developer: If you narrowed down which mod caused the error, then you can reach out to them via CurseForge or Modrinth to see if they can assist or patch it in an update.

5. Server Lag & Low TPS

The Cause: Modded servers are highly resource-intensive. Excessive automated machinery, chunk loaders, massive mob farms, or poorly optimized mods can cause the server’s Ticks Per Second (TPS) to drop far below the ideal 20 TPS.

How to Fix:

1. Run a Profile: Use optimization tools like Spark. Run the command /spark profiler start, wait a few minutes, and run /spark profiler stop to generate a performance link.
2. Analyze the Results: Check the Spark report to find which mod or entity type is consuming the highest percentage of CPU cycles.
3. Apply Limits: Advise the customer to remove chunk loaders, limit automated pipe systems (like Pipez or Mekanism cables), or replace heavy mods with optimized alternatives.

Plugin Troubleshooting – Minecraft

1. Red Plugin Status in /plugins

The Cause: A red plugin name in the /plugins list indicates that the server recognized the plugin file, but it failed to enable during startup.

1. Outdated/Unsupported Version: The plugin version does not support the current server version.
2. Missing Soft/Hard Dependencies: The plugin requires another plugin to run (e.g. an economy plugin that requires Vault).
3. Java Version Conflict: The plugin was compiled with a newer version of Java than what the server is currently running.

 
How to Fix:

1. Check latest.log: Restart the server and search the console log for the name of the red plugin. Look for words like Severe, Exception, or Error during initialization.
2. Install Dependencies: If the log says Missing Dependency: [PluginName], download and install that background plugin.
3. Update the Plugin: Ensure the user has downloaded the correct jar build meant for their specific server software (Paper, Spigot, etc.).

2. YAML Syntax Errors in Config Files

The Cause: This is a YAML Syntax Error. Minecraft plugins use .yml files for configuration. YAML is incredibly strict about indentation and formatting. This error usually means the user used the Tab key instead of spaces, missed a colon :, or messed up the alignment of the configuration lines.

How to Fix:

1. Locate the File: The console error will usually tell you which file (e.g., config.yml) and what line number is broken.
2. Use a Validator: Our built-in file editor should identify the line that’s causing issues, but you can always use a third-party validator instead. It will point out the exact line and character causing the break.
3. Fix Formatting: Ensure no Tab keys were used (only spaces) and that all open quotation marks are closed properly.

3. ‘No Permission’ Errors for Server Owners

The Cause: Being a server operator gives you vanilla Minecraft admin permissions, but some plugins ignore the /op status entirely. Instead, they rely strictly on a Permissions Plugin (like LuckPerms). If a permission plugin is active, it blocks commands by default until they are explicitly granted.

How to Fix:

1. Check for Permission Plugin: Verify if the server has a permission manager installed.
2. Give Permission: If using LuckPerms, the owner needs to assign themselves the global admin permission node (*) via the server console.
3. Console Command: lp user [Username] permission set * true
4. Check Documentation: Look up the plugin’s specific documentation page to find the exact permission nodes required to execute the locked commands (e.g., essentials.fly for the /fly command).

 
⚠️ In some cases, having no permissions to a command could mean the plugin is encountering errors. Check the server log to find out more information.
 

4. MySQL Database Connection Failures

The Cause: Large-scale plugins (like CoreProtect, LuckPerms, or LogBlock) often use external databases to store data efficiently. If the credentials in the plugin’s config.yml are incorrect, or if the external database is offline/blocking the server’s IP, the plugin will fail to connect and often disable itself.

How to Fix:

1. Verify Credentials: Cross-reference the database hostname, port, database name, username, and password in the plugin’s config file with the actual details provided in the Apex Hosting panel.
2. Check Access Rules: Ensure the database allows external connections if the database is hosted on a different machine than the gameserver.
3. Fallback to SQLite: If you don’t explicitly need a MySQL network setup, change the storage type back to sqlite or local in the config file so it saves directly to the server folder without requiring an external connection.

5. ‘Unknown Command’ for Active Plugins

The Cause: This occurs when two or more plugins are trying to use the exact same base command (e.g., multiple plugins trying to use /spawn or /shop), resulting in a command conflict where one plugin overrides the other completely. It can also happen if the command is being blocked by a world guard manager or if it’s simply entered incorrectly.

How to Fix:

1. Use Plugin Overrides: Most plugins allow you to use an explicit prefix to force the command. For example, if Essentials and another plugin conflict over /feed, the user can type /essentials:feed to bypass the conflict.
2. Modify commands.yml: Check the commands.yml file in the server’s root folder. You can create an alias here to redirect commands safely OR install an alias plugin that can do that for you.
3. Check Configuration Files: Look into the config files of the conflicting plugins. Many developers include an option to disable specific commands if they know conflicts are likely.

Conclusion

Troubleshooting mods and plugins on your Minecraft server can be a challenging task at first, but don’t worry! When you know how to read the signs, most of these issues boil down to simple version mismatches or formatting errors. Keep your files organized, check your server logs regularly, and isolate problems systematically so you can resolve these common errors on your own.

Still Stuck? If you’ve walked through these steps and your server is still giving you trouble, don’t sweat it. Our 24/7 Support Team is always available. Open a support ticket or jump into live chat, and our team will help you get your server back up and running.