How to update a Minecraft plugin for a new Minecraft version

A plugin that worked on your old server version may stop loading, or load and misbehave, after you update Minecraft. Here is what usually changes and how to bring the plugin along.

Within the same version line

Updating from 1.20.1 to 1.20.4 almost never breaks a plugin, because the Bukkit API stays the same inside a line. Most plugins just keep working.

Across lines

• The api-version in plugin.yml is older than the server. Newer servers still load it with compatibility handling, but you should raise it after testing.
• The Java version rises. Minecraft 1.20.5 and newer need Java 21, and the 26.x versions need Java 25. The plugin does not need to change for that, but the server does.
• Methods and materials were removed or renamed. A plugin that calls them fails at runtime.

What to do

1. Make a backup and test on a copy of the server.
2. Start the new version and read the console for errors with the plugin name.
3. If it loads and works, change api-version to the new line and keep using it.
4. If it breaks, rebuild the plugin for the new version. With a generator you pick the new version and compile again.
5. If it still fails, tell the chat what error you see and ask it to adapt the code.

The old materials problem

The biggest break in history was 1.13, when item and block names were renamed. A plugin written for 1.12 and earlier uses the old names and needs to be rewritten for 1.13 or newer, not just rebuilt.

Keep your source

The best way to survive updates is to have the source. Then rebuilding for a new version takes a minute, instead of hunting for a new download of a plugin whose author stopped updating it.

A short update plan

1. Read the new version's notes for API removals that affect your plugins.
2. Check that your server software has a stable build for the version.
3. Update Java if the new line needs it.
4. Back up, then update the server on a copy.
5. Rebuild your own plugins for the new version and check third-party plugins for updates.
6. Test, then update production in a quiet hour.

When a third-party plugin has no update

Look for a maintained fork or a similar plugin. If you need only a small part of it, describe that part and generate a replacement. Do not keep running an abandoned plugin on a new version, because it can fail in ways that corrupt data.

Frequently asked questions

How soon after a release should I update?

Wait for a stable server build and for your key plugins to support it, which is often a few weeks.

Can I downgrade a world?

No. Worlds are not downgrade safe, so always keep a backup from before the update.

Does a rebuild change behavior?

It should not, but the API can change underneath. Test the features again after a rebuild.