Guide

How to fix Minecraft plugin errors

Updated October 18, 2026

When a plugin does not load, the server almost always says why: the reason is in the console during startup, a few lines above or below the plugin's name. Learn to read that part of the log and most errors take a minute to fix. Here are the common ones and what they mean.

Say your server version and what the plugin should do.

Generate this with Codexe

Step by step

1.Open the log of the startup
Read the console, or logs/latest.log in the server folder. On a hosting panel, use its console or file manager.
2.Search for the plugin's name
Find the first error that mentions it. Lines starting with [ERROR] or [WARN] and a stack trace below them are the ones that matter.
3.Read the first and the "Caused by" lines
The first line says what failed; the last Caused by: line usually says why. Lines with the plugin's own package name show where in its code.
4.Match it to the list below
Most startup errors are a version, Java or dependency problem, and the message says which.
5.Fix one thing and restart
Change one thing, restart (not /reload) and read the log again. Errors from one plugin can cause errors in others.

The common errors

You see	What it means	Fix
`Unsupported API version 1.21`	The plugin's `api-version` is newer than your server.	Get the version for your server, or update the server.
`Could not load 'plugins/X.jar'` with `Invalid plugin.yml` or `Jar does not contain plugin.yml`	The plugin's descriptor is missing or has a YAML error, or the file is not a plugin.	Check you downloaded the plugin and not its source, a mod or a zip. If you built it, fix `plugin.yml`.
`UnsupportedClassVersionError`, "class file version 65.0"	The plugin needs a newer Java than the server runs (61 = Java 17, 65 = Java 21, 69 = Java 25).	Run the server on that Java, or rebuild the plugin for your Java.
`NoClassDefFoundError` or `ClassNotFoundException`	A class the plugin needs is not there: a dependency plugin is missing, a library was not shaded into the .jar, or the API does not exist on this version.	Install the plugin named in the error (Vault, ProtocolLib), or use a build for your version.
`Unknown/missing dependency plugins`	A plugin listed in `depend` is not installed.	Install it in `plugins/`.
`Error occurred while enabling X (Is it up to date?)`	The plugin loaded but crashed in `onEnable`.	Read the `Caused by` line: often a config error or a missing dependency.
`Ambiguous plugin name`	Two .jar files of the same plugin are in `plugins/`.	Delete the old one.

Errors that are not about loading

The plugin is green but a command says "Unknown command": the command is missing from plugin.yml, or another plugin uses the same name.
"I'm sorry, but you do not have permission": the player lacks the permission node. Check the plugin page for the node and give it with your permissions plugin.
Errors after editing config.yml: YAML needs spaces, not tabs, and quotes around text with : or & at the start.
Works after a restart, breaks after /reload: the plugin does not support /reload. Restart instead.

Which Java your server needs

Minecraft 1.20.5 and newer need Java 21, and 26.x needs Java 25; 1.18 to 1.20.4 need Java 17. Run java -version with the same Java the server uses (on a hosting panel it is usually a setting called Docker image or Java version). A plugin built for an older Java runs on a newer one, not the other way around.

Fixing plugins made with Codexe

Plugins made on Codexe are compiled for the version you chose and checked for a valid plugin.yml before they are Ready. On a test server, the Logs tab shows the log live with errors highlighted, and Export logs saves it as a file. Describe what you see in the project chat ("the plugin is red in /plugins and the log says ...") and Codexe changes the code and builds again. If a Compile fails on files exactly as Codexe delivered them, Fix with AI repairs them for free.

Questions

Where is the server log?

logs/latest.log in the server folder, for the current run. Older runs are in the same folder as .log.gz files.

Can one plugin break another?

Yes: a missing or broken dependency stops every plugin that needs it. Fix the first error in the log before the others.

Is it safe to share my log?

Mostly, but check it first: logs can contain IP addresses and, with some plugins, database passwords from errors.

Rebuild a broken plugin for your server

This prompt opens ready to send:

“A Paper 1.21.4 plugin called SimpleWarps that replaces my old one that no longer loads: /setwarp, /warp and /delwarp with a name, /warps lists them in a GUI, permission warps.admin to set and delete, warps saved across restarts, messages in config.yml.”