Announcement Paper & Velocity 1.20.6

The 1.20.5/6 Update​

Stable Paper and Velocity 1.20.6 builds have been released! As always, backups are absolutely mandatory. After upgrading your world to 1.20.6, you cannot downgrade back to a lower version!

The reason for the stable announcement arriving so late is that upstream's item handling has shown to be incredibly broken after the 1.20.5 changes to items. Unfortunately, there still remain a good number of smaller issues with ItemMeta API<->vanilla conversion, but at this point we should have gotten rid of the nastier ones. In any case, please make sure to report any such issues or missing functionality on our issue tracker.

We would like to thank everyone that worked on this update (a lot of people and work were needed for a minor update, once again):

If you'd like to support PaperMC as a whole, you can find more information at

Java 21 requirement​

Minecraft 1.20.6 requires you to run Java 21. See here on how to update your installed Java version.

Item format changes​

Mojang has drastically revamped the way itemstacks store their data. While they are still serialized to raw NBT in chunk and entity files, this is no longer true for commands and storage at runtime. We have created an item command converter page ( where you can update your commands etc. If you are a developer, see the below section on how this might affect you.

Unlike vanilla/Spigot, Paper will also automatically upgrade commands in command blocks as well as text components in signs when upgrading from an older server version. If you for whatever reason do not wish to have these upgraded, you can use the Paper.DisableCommandConverter system property/startup flag. For this reason, we also highly discourage upgrading your old world with non-Paper servers.

Note that the hide-item-meta config option has not yet been updated, but everything else should work as expected.

spawnChunkRadius gamerule​

Our keep-spawn-loaded and keep-spawn-loaded-range config options have been removed, as Mojang has added the spawnChunkRadius gamerule, serving the same function.

For Developers​

Mojang-mapped runtime without CB package relocation​

As announced previously, we have dropped Spigot's mix of partially obfuscated, partially Mojang mapped, and partially Spigot mapped runtime names of classes, methods, and fields. On top of that, we have dropped the arbitrary CraftBukkit package relocation version. Plugins compiled against the reobfuscated server will still work via magical plugin remapping that is applied once on startup, as well as reflection rewriting. However, we highly recommend using paperweight-userdev to offer plugin jars targeting the mapped server, even if just as a secondary jar, as it would greatly benefit the vast majority of your users (well over 80-90%).

If you are not using internals and thus run on a Mojang mapped server fine, you should exclude your plugin from being remapped by adding the Mojang-mapped marker to the jar manifest (setting paperweight-mappings-namespace to mojang). Alternatively, you can add the entry manually in your gradle or maven build scripts.

Brigadier Command API​

We have finally added more powerful API to interact with Brigadier commands directly. Brigadier is the command library vanilla uses for creating and parsing commands, meaning you can add much nicer auto-completions and argument handling for your commands, although this will be most interesting for command libraries wrapping around Brigadier. Basic usage is explained on our docs page.

ItemStack and ItemMeta​

If you were using API to modify item data, then you are largely fine. Since we have long deemed moving away from raw NBT data storage inevitable, we have never added API for interacting with the underlying NBT data directly. As such, only plugins unnecessarily mutating items through internals should break. The persistent data container API is also not affected. For item serialization, we highly recommend using our ItemStack#serializeAsBytes method over Spigot's config serialization, so that you can guarantee proper upgrade paths, compatibility for stored items, and better performance.

ItemMeta is very much not compatible with the idea of storing any data on any item, e.g. adding durability to a book, or making stone eatable. While we have tried our best at making sure that such custom data is not lost, the API has no proper way of applying these at the moment. On top of that, a lot of Spigot API that previously assumed a specific set of hardcoded enums, such as banner patterns, break when trying to add custom ones. We currently have a better system for this in the works, but it will take some more time before it is fully ready.

Finally, a lot of item data now has hard limits for size and length, such as lore being limited to 256 entries - most of these you shouldn't really run into. The most notable example is player profiles (including player head profiles), where player names can no longer exceed 16 characters and are limited to printable ascii characters. We strictly enforce these everywhere, as otherwise it could lead to chunks and player data unable to be saved, as well as inventory or player info updates erroring on the client.

canPlaceOn and canBreak break​

Another piece of broken API is our canPlaceOn and canBreak methods, as these have had major changes that can now longer accurately be represented by just a list of materials. New API for this will also be added soon.

ItemFlag behavioral changes​

Unlike before, you can no longer set most of the hide item flags without the data in question, e.g. you need to set can_place_on data in order to hide it.

That's it​

Finally, here is a closing note from our master of words, electroniccat:
as always, BACKUP YO SHIT, so long, and thanks for the fish
Something I want to mention for those that are curious: The name length limit for profiles will also affect the displayed online players on a server list's hover on the player count, given that (for whatever reason) the full profile is sent to the client there, so keep that in mind.
I proposed to have some way of bypassing this limit for this particular case (And maybe other cases), but until something is there, you'll have to work with a workaround here (Making a custom class extending PlayerProfile and use that)