What Changed in Paper 1.21, Migration Guide

Paper 1.21: What Server Owners Need to Know

Paper 1.21 is not just a version bump, it carries meaningful changes to configuration, internals and the API surface that plugin developers rely on. Whether you run a small SMP or a large network, understanding what moved, what broke and what improved will save you hours of debugging. This guide covers the practical migration steps rather than rehashing Mojang's snapshot changelog.

If you have not yet done the basic update steps (backup, Java check, plugin audit), start with our 1.21 update guide first. This page assumes you are past that stage and want to understand Paper-specific changes.

Java 21 Is Now Mandatory

Paper 1.21 will not start on Java 17 or earlier. The server will print an error and exit immediately if it detects an older JVM. This is not a Paper decision, Mojang's own server jar requires Java 21 starting with 1.20.5, and Paper follows upstream requirements.

If your host uses Pterodactyl, you need a Docker image with Java 21. Common image names include ghcr.io/pterodactyl/yolks:java_21. Check our Java 21 vs Java 17 guide for installation steps on various platforms.

Configuration File Changes

Paper has been gradually restructuring its configuration over the past several versions. In 1.21, a few more options moved or got renamed. Here is what to watch for.

paper-global.yml

The global config continues to replace the old paper.yml. If you are migrating from a much older version (1.18 or earlier), your old paper.yml will be automatically converted, but review the result manually. Automatic migration does not always preserve comments or understand custom values.

paper-world-defaults.yml

Per-world settings live here (or in per-world override files). Key changes in 1.21:

• Entity activation range: Defaults have been adjusted for new mob types added in 1.21. If you had custom activation ranges, verify they still make sense with the new mobs included.
• Anti-xray: The engine mode settings remain the same, but the default block list has been updated to include new ore and block types. If you maintain a custom list, add the new blocks or players will be able to see them through xray.
• Spawn limits: Review spawn-limits sections. New mob categories or changes to existing category assignments may affect your mob caps.

Removed or Renamed Settings

Old Setting	Status	Replacement
use-faster-eigencraft-redstone	Removed	Alternate redstone is now always active in Paper
Various paper.yml flat settings	Migrated	Moved to paper-global.yml or paper-world-defaults.yml in structured format
Some anti-cheat-adjacent tick settings	Renamed	Check Paper docs, names changed to be more descriptive

After your first 1.21 startup, open the generated config files and diff them against your old ones. Any setting that Paper did not recognize will be logged as a warning in the console.

API Changes That Affect Plugins

This is where most breakage happens. Paper's API evolves alongside Minecraft's codebase, and 1.21 brought several changes that plugin developers need to address.

Component API Adoption

Paper has been pushing the Adventure Component API as the standard for all text handling. In 1.21, more legacy methods that accepted raw strings have been deprecated or removed. Plugins that still use setCustomName(String) on entities may need to switch to customName(Component). If you see warnings about deprecated text methods in your console, the plugin needs an update from its developer.

Registry Changes

Minecraft 1.21 expanded the data-driven registry system. Enchantments, for example, are now more deeply integrated into the registry rather than being hardcoded enums. Plugins that reference enchantments by their old enum names (like Enchantment.DAMAGE_ALL) may find those fields missing or behaving differently. This particularly affects custom enchant plugins and loot table manipulators.

Entity and Block Changes

• New entity types added in 1.21 (breeze, bogged, etc.) need to be accounted for in plugins that handle mob events, spawning rules or entity limits.
• New block types (trial spawner, vault block, copper variants) may need to be added to protection plugin configs like WorldGuard's block lists.
• Changes to the wind charge and mace mechanics affect combat plugins and anti-cheat systems.

Chunk System Behavior

Paper's async chunk system has seen incremental improvements. In 1.21, chunk loading and generation are slightly faster due to optimizations in the scheduling pipeline. You should not need to change any chunk-related settings, but if you previously used aggressive chunk loading limits to prevent lag, consider relaxing them slightly and monitoring whether performance improves.

The chunk ticket system, which controls why chunks stay loaded, may behave slightly differently for plugins that create custom chunk tickets. Plugin developers should review Paper's chunk loading API docs for 1.21 specifics.

Performance Improvements

Paper 1.21 includes several performance wins over 1.20:

• Entity AI optimizations: Pathfinding calculations for certain mobs are more efficient, reducing tick time in mob-heavy areas.
• Block update batching: Redstone and fluid updates are batched more aggressively, which helps in areas with complex contraptions.
• Memory usage: Java 21's improved garbage collector (especially ZGC) works better with Paper's allocation patterns, resulting in fewer GC pauses. If you were using G1GC, consider testing ZGC with -XX:+UseZGC -XX:+ZGenerational flags.

Run a Spark profiler report before and after migration to compare tick times and identify any regressions. Refer to the optimization guide for Spark usage and JVM flag recommendations.

Which Plugins Typically Need Updates

Based on historical patterns, these plugin categories almost always need updates for major Minecraft versions:

• ProtocolLib and packet-based plugins: Protocol changes every version. ViaVersion, ProtocolLib, PacketEvents and anything that sends raw packets will need version-specific builds.
• Hologram plugins: Display entity behavior may change. DecentHolograms and HolographicDisplays usually release updates within days of a new version.
• WorldEdit/WorldGuard: Usually compatible quickly, but may need updates for new block types. Grab the latest dev build from EngineHub.
• Citizens: NPC plugins interact deeply with entity internals. Citizens typically has a 1.21 build available shortly after release.
• Vault and economy: Vault itself rarely breaks, but economy plugins behind it might. Test transactions after updating.

NeoForge and Fabric Compatibility

Paper is a Bukkit/Spigot fork and does not natively support Forge or Fabric mods. However, some server owners use hybrid solutions. For 1.21:

• NeoForge (the successor to Forge) has its own 1.21 builds. It is a separate server platform, not compatible with Paper plugins.
• Fabric has 1.21 support through updated Fabric Loader and Fabric API. Not compatible with Paper plugins.
• Hybrid platforms like Arclight or Mohist attempt to run Bukkit plugins alongside Forge mods. These are fragile, lag behind on updates and are generally not recommended for production use.

If you need mods, run a dedicated Fabric or NeoForge server. If you need plugins, stick with Paper or Purpur. Trying to do both creates more problems than it solves.

How to Read Paper's Changelog

Paper does not publish a traditional changelog like commercial software. Instead, track changes through these sources:

• Paper GitHub: The commit history on the main branch shows every patch. Look at commits tagged with "API" for changes that affect plugins.
• PaperMC Discord: The #announcements channel covers major changes. The #paper-help channel is where server owners discuss migration issues.
• Paper documentation: docs.papermc.io has migration guides for significant API changes between versions.
• Build page: Each build on papermc.io/downloads lists the commits included since the previous build.

When you download a Paper build, note the build number. If you encounter a bug, you can report it with the exact build number and the Paper team can identify whether it is a known issue or a regression.

Need hosting for your network? Astroworld Hosting offers NVMe SSD, Pterodactyl panel, and DDoS protection. See features , plans from €6.39/mo.