How to update a plugin to a new Minecraft version

Step by step

1. 1.Try the old .jar first

   Put it on a test server of the new version and read the console. If it loads and works, you may not need to change anything.

2. 2.Change the API dependency

   In pom.xml or build.gradle, set paper-api or spigot-api to the new version.

3. 3.Update api-version and Java

   Set api-version in plugin.yml (for example '1.21') and compile for the Java the new version needs: Java 17 before 1.20.5, Java 21 from 1.20.5, Java 25 for 26.x.

4. 4.Fix what no longer compiles

   Build and go through the errors: renamed materials, removed methods, changed event classes. The compiler lists them with file and line.

5. 5.Update dependencies

   Plugins your plugin uses (Vault, PlaceholderAPI, ProtocolLib, WorldGuard) need versions that support the new Minecraft version too, both in the build file and on the server.

6. 6.Test on the new version

   Load it on a server of the new version with the same plugins, and try every command and feature, not only startup.

What usually breaks

• Material and enum names: the 1.13 update renamed most items and blocks; later versions add, rename or remove some. Code that uses old names or numeric ids fails.
• Deprecated methods removed: methods marked deprecated for several versions eventually disappear.
• Item data: from 1.20.5, item NBT was replaced by data components. Plugins that edit item NBT directly need a rewrite of that part; the normal ItemMeta API keeps working.
• NMS and reflection: code that uses internal server classes breaks on almost every version. Replace it with the API where possible, or with a library such as ProtocolLib.
• Library versions: shaded libraries built for an older Java can fail on the new one.

Updating across many versions

Going from 1.8 or 1.12 to 1.21 is closer to a rewrite of the parts that touch items, blocks and particles than to an update. Do it in one go against the new API, not version by version, and expect the config files to need new material names too.

If the plugin must support several versions at once, compile against the oldest one you support and avoid API added later, or use separate builds per version.

With Codexe

On Pro and above you can import the plugin's source as a ZIP and ask, for example, "This is my Paper 1.20.4 plugin. Update it to Paper 1.21.4". Codexe reads the Minecraft version from the build file, builds with the Java that version needs, and repairs compile errors using the real signatures of the API it builds against. For a plugin you made on Codexe, ask for the new version in the project chat.

Compiling proves the plugin builds on the new API. Then try it on a test server, because behaviour changes between versions do not show up as compile errors.

Questions