How to Troubleshoot and Fix a Minecraft Mod

When a Minecraft mod or plugin breaks, it can feel like anything could be wrong. The good news is that most problems fall into a handful of categories. Walk through these five steps in order and you will either fix the issue yourself or gather enough detail to get fast help.

#1. Define what is broken

Vague reports slow fixes. Write down the exact failure first.

• What were you trying to do when it failed?
• What should happen versus what actually happens?
• Is it a crash, missing item, or nothing happens?

#2. Verify your versions line up

Most mod issues are version mismatches.

• Minecraft version
• Mod loader or server platform version (Fabric, Forge, NeoForge, Spigot, Paper)
• Mod or plugin version built for that platform
• Java version if the mod lists a requirement

#3. Confirm the mod is installed and enabled

Make sure the server actually sees the file.

• The file is in the correct folder: mods or plugins
• Startup logs show the mod or plugin loading
• It appears in the Mods or Plugins list in-game

#4. Check logs for errors

Logs usually tell you why the mod failed.

• Scan startup logs for ERROR lines near the mod name
• Look for missing dependencies or loader errors
• If it crashed, grab latest.log and the crash report

#5. Troubleshoot commands and features

Commands fail in two different ways: not registered or erroring.

• Does the command show in tab completion or /help?
• When you run it, does an error appear in chat or console?
• If nothing happens, note that detail for support

Tip: If the mod never shows up in console logs or the Mods list, it is not loading. That almost always points to a version mismatch, missing dependency, or a file in the wrong folder.

#What to include when asking for help

• Exact mod or plugin name and version
• Minecraft version, loader or platform version, and Java version
• Steps to reproduce, including what you expected to happen
• latest.log plus any crash reports or error screenshots
• List of other mods or plugins installed