TroubleshootingMinecraft Plugin Not Loading

Minecraft Plugin Not Loading? Common Causes & Fixes

Diagnose Minecraft plugins that do not appear, fail to enable, show red in /plugins or stop working after an update.

Minecraft Plugin Not Loading? Common Causes & Fixes

If a Minecraft plugin is missing from /plugins, appears red, or fails during startup, the cause is usually the server platform, JAR location, Java version, a missing dependency or an error in the startup log. Check these in order before reinstalling everything.

Identify what “not loading” means

SymptomWhat it usually indicates
Plugin is not listed at allWrong folder, wrong file, unsupported server software or the server has not restarted
Plugin appears red in /pluginsIt was discovered but failed to enable
Console reports a missing dependencyA required plugin or library is not installed or did not load
Plugin worked before a server updateThe plugin build or one of its dependencies may no longer be compatible
Plugin loads but its commands do not workPermissions, command conflicts or disabled settings may be responsible

1. Check the server software

Most Bukkit-style plugins are made for compatible server software such as Paper, Spigot or Purpur. They do not load directly on a Vanilla server, and Fabric, Forge or NeoForge mods are not Bukkit plugins.

Check the product listing and the plugin developer's compatibility notes. Proxy plugins may need to run on Velocity or BungeeCord rather than in the backend server's plugins folder.

2. Check the JAR file and folder

  1. Stop the server.
  2. Open the active server directory and confirm you are using its plugins folder.
  3. Check that the downloaded file is the actual .jar, not a ZIP archive or a mod for another loader.
  4. Make sure the JAR is directly inside the correct plugins folder unless the developer specifies another location.
  5. Remove duplicate or older copies of the same plugin, keeping a backup.
  6. Start the server and check the console.

Do not replace plugin JARs while the server is running.

3. Check Java and Minecraft compatibility

A plugin can require a newer Java runtime or a specific Minecraft/server API. Compare all of these with the plugin's release notes:

  • Minecraft version
  • Server software and build
  • Java runtime version
  • Plugin version
  • Required dependencies

An UnsupportedClassVersionError commonly indicates that the Java runtime is older than the version used to build the plugin. Check the server's startup log and the official requirements for the exact Minecraft release rather than guessing.

See How to Check Minecraft Plugin Compatibility.

4. Read the first relevant startup error

Open the console or logs/latest.log and search for the plugin's name. Start with the first error associated with it; later stack-trace lines may be consequences of the original failure.

Look for messages such as:

  • UnknownDependencyException — a required plugin is missing or failed to load.
  • UnsupportedClassVersionError — the runtime Java version is too old.
  • InvalidPluginException or InvalidDescriptionException — the file may be invalid, incomplete or not a compatible plugin.
  • API or version warnings — the plugin may not support the running server build.

Install dependencies only from their official sources and verify that each dependency supports your server version.

5. Check configuration and permissions

If the plugin enables successfully but a feature or command does not work:

  • Check the plugin's own command syntax and configuration.
  • Verify the player's effective permission nodes.
  • Check whether another plugin registers the same command.
  • Confirm that required features or modules are enabled.
  • Look for YAML errors or unsupported configuration keys.

For configuration packs, use Minecraft Config Pack Troubleshooting. For permission or command issues, also check the product README.

6. Isolate plugin conflicts safely

Back up the server first. If the problem began after adding a plugin, temporarily move that plugin out of the active folder and restart. If necessary, test plugins in small groups to narrow down the conflict. Keep dependencies together and do not delete plugin data while diagnosing.

Avoid using /reload as a general fix. Use a full restart unless the plugin explicitly documents a safe reload procedure.

Still not working?

Contact ZCraft Studios support if the issue involves one of our products. Include the product and release version, Minecraft and server versions, Java version, dependencies, and the first relevant console error. Remove tokens, passwords and private player data before sharing logs.

For upstream plugin failures, also consult the plugin developer's official documentation or issue tracker.