---
title: "Update a Paper Plugin for Minecraft 26.1: Java 25 Guide"
description: "Developer guide to updating a Paper plugin to Minecraft 26.1+: Java 25, Paper API versions, api-version, world storage changes and testing."
url: "https://www.zcraftstudios.com/blog/update-paper-plugin-to-minecraft-26-1"
updated: "2026-10-27T04:59:29.068351+00:00"
source: "ZCraft Studios"
---

> Site index for AI agents: https://www.zcraftstudios.com/llms.txt (full reference: https://www.zcraftstudios.com/llms-full.txt). Every page is available as Markdown by adding `.md` to its URL or sending `Accept: text/markdown`.

1. [Home](https://www.zcraftstudios.com/)
2. [Blog](https://www.zcraftstudios.com/blog)
3. Update a Paper Plugin for Minecraft 26.1: Java 25 Guide

[ All posts](https://www.zcraftstudios.com/blog)

# Update a Paper Plugin for Minecraft 26.1: Java 25 Guide

ZCraft StudiosOct 27, 2026

Developer guide to updating a Paper plugin to Minecraft 26.1+: Java 25, Paper API versions, api-version, world storage changes and testing.

## In this guide

- [What changed for plugin developers](#what-changed-for-plugin-developers)
- [Step 1: update the toolchain](#step-1-update-the-toolchain)
- [Step 2: update the Paper API dependency](#step-2-update-the-paper-api-dependency)
- [Step 3: set api-version](#step-3-set-api-version)
- [Step 4: fix world and dimension assumptions](#step-4-fix-world-and-dimension-assumptions)
- [Step 5: check deprecations and removals](#step-5-check-deprecations-and-removals)
- [Step 6: Folia and threading](#step-6-folia-and-threading)
- [Step 7: test on a real server](#step-7-test-on-a-real-server)
- [Release and support notes](#release-and-support-notes)
- [Frequently asked questions](#frequently-asked-questions)
- [Related reading](#related-reading)

## Update a Paper Plugin to Minecraft 26.1: Java 25 and api-version

**Quick answer:** to update a Paper plugin for Minecraft 26.1 or newer, build with **Java 25**, point your Paper API dependency at the new `26.1.x` version, set `api-version` in `plugin.yml`, fix anything that assumed the old world folder layout, then test on a real 26.x server.

_For server owners rather than developers, see [Update a Minecraft Server to 26.1+](https://www.zcraftstudios.com/blog/minecraft-26-1-server-update-guide). Check the Paper developer documentation for the exact current snippets, because dependency coordinates and build numbers change._

## What changed for plugin developers

| Change | Impact |

| --- | --- |

| Java 25 baseline | Compile and run on Java 25 |

| Year-based Minecraft versions | `26.1`, `26.1.2`, `26.2`, ... replace `1.21.x` |

| New Paper version format | `<mcversion>.build.<build>-<status>`, for example `26.1.2.build.23-alpha` |

| Paper no longer uses the old `-R0.1-SNAPSHOT` scheme | Update your dependency version |

| World storage | Dimensions live under `world/dimensions/<namespace>/<key>/` |

| Per-world Paper config | `paper-world.yml` moved into dimension folders |

## Step 1: update the toolchain

Install a Java 25 JDK, set your build to use it, and update your CI. Example Gradle toolchain:

```
java {
    toolchain {
        languageVersion.set(JavaLanguageVersion.of(25))
    }
}
```

In Maven, set the compiler release to 25\. Update GitHub Actions or other pipelines that still use Java 21.

## Step 2: update the Paper API dependency

Use the Paper repository and the new version format. Example Gradle:

```
repositories {
    maven("https://repo.papermc.io/repository/maven-public/")
}

dependencies {
    compileOnly("io.papermc.paper:paper-api:26.1.2.build.+")
}
```

Pin a specific build for reproducible releases when you are ready to publish. Use the version coordinates shown in the Paper docs, since they are the source of truth.

## Step 3: set api-version

In `plugin.yml`:

```
name: MyPlugin
version: 1.0.0
main: com.example.myplugin.MyPlugin
api-version: '26.1.2'
```

`api-version` tells the server which API your plugin was built for. Since Minecraft 1.20.5, minor versions can be specified. Setting it too low can cause the server to apply compatibility handling, and setting it higher than the server fails to load the plugin.

## Step 4: fix world and dimension assumptions

Code that builds file paths to the old dimension folders will break. Use Bukkit and Paper world APIs rather than hard-coded folders, and resolve worlds by key. Common cases:

- Pregeneration, backup and world tools that touched `world_nether` and `world_the_end`
- Code that reads or writes region files directly
- Anything that depended on a per-world `paper-world.yml` in the root world folder

Dimension keys such as `minecraft:overworld`, `minecraft:the_nether` and `minecraft:the_end` identify worlds in the new layout, and custom dimensions use `namespace:key`.

## Step 5: check deprecations and removals

Read the Paper release notes and the Javadoc for the version you target. Fix compiler warnings, replace removed or renamed methods, and rebuild. If you use NMS or internals, expect more work and consider using the API instead.

## Step 6: Folia and threading

If you support Folia, set `folia-supported: true` only after you have reviewed your use of the scheduler, entities and world access for regions. Many plugins are not Folia-safe. See [Folia vs Paper vs Purpur](https://www.zcraftstudios.com/blog/minecraft-server-software-paper-purpur-folia).

## Step 7: test on a real server

1. Run a clean Paper 26.x server with Java 25.
2. Start with a fresh world and an upgraded world.
3. Test every command, listener and config reload.
4. Test with other common plugins. See [Plugin Conflicts](https://www.zcraftstudios.com/blog/minecraft-server-plugin-conflict-debugging).
5. Run [spark](https://www.zcraftstudios.com/blog/how-to-read-spark-profiler-minecraft) and check for new lag.
6. Back up before testing against real data. See [Staging Environment Guide](https://www.zcraftstudios.com/blog/minecraft-server-staging-environment-guide).

## Release and support notes

- Publish separate builds for older Minecraft versions if you still support them.
- State supported versions and Java requirements on your plugin page.
- Update the changelog with the new `api-version` and any breaking changes.
- Remind users to follow the update order in [the server update guide](https://www.zcraftstudios.com/blog/minecraft-26-1-server-update-guide).

## Frequently asked questions

**What Java version do I need for Minecraft 26.1 plugins?** Java 25.

**What is the new Paper API version format?** `<mcversion>.build.<build>-<status>`, such as `26.1.2.build.23-alpha`.

**What should api-version be?** The Minecraft version you built against, for example `26.1.2`.

**Why does my plugin fail to find the Nether world folder?** Dimension folders moved under `world/dimensions/`.

**Do I need to rewrite my plugin?** Usually not, but code that touched files or internals may need changes.

## Related reading

- [Custom Minecraft Server Development: When to Hire](https://www.zcraftstudios.com/blog/custom-minecraft-development)
- [Minecraft Plugin Config Review](https://www.zcraftstudios.com/blog/minecraft-plugin-config-review-checklist)
- [Plugin Not Loading?](https://www.zcraftstudios.com/blog/minecraft-plugin-not-loading-fix)

## Continue reading

- [Update a Minecraft Server to 26.1+: Java 25, Paper, Plugins](https://www.zcraftstudios.com/blog/minecraft-26-1-server-update-guide)
- [ZGC for Minecraft Servers: Flags, Java Versions, G1 Choice](https://www.zcraftstudios.com/blog/zgc-minecraft-server-flags-guide)
- [Paper Anti-Xray Settings: Engine Modes and Testing](https://www.zcraftstudios.com/blog/paper-anti-xray-settings-guide)
- [Paper Reload vs Restart: Why Plugins Break After /reload](https://www.zcraftstudios.com/blog/paper-reload-versus-restart-explained)

[ Previous guide EssentialsX Permissions: Nodes, LuckPerms Setup and Examples](https://www.zcraftstudios.com/blog/essentialsx-permissions-guide-luckperms)[ Next guide Update a Minecraft Server to 26.1+: Java 25, Paper, Plugins](https://www.zcraftstudios.com/blog/minecraft-26-1-server-update-guide)

<script type="application/ld+json">{"@context":"https://schema.org","@type":"Organization","@id":"https://www.zcraftstudios.com/#organization","name":"ZCraft Studios","alternateName":["ZCS","ZCraft","ZCraftStudios"],"logo":{"@type":"ImageObject","url":"https://www.zcraftstudios.com/img/apple-touch-icon.png","width":180,"height":180},"url":"https://www.zcraftstudios.com","description":"ZCraft Studios (ZCS) creates Minecraft plugins, server configs and tools. Browse resources, compatibility details and setup guides.","email":"Support@zcraftstudios.com","slogan":"Minecraft resources, configurations and custom server development.","knowsAbout":["Minecraft plugins","Minecraft server configuration","Java plugin development","Minecraft server optimization"],"sameAs":["https://dsc.gg/zcraftstudios","https://x.com/ZCraftNetwork","https://www.youtube.com/@zcraft_studios","https://www.instagram.com/ZCraftStudios"],"contactPoint":[{"@type":"ContactPoint","contactType":"customer support","email":"Support@zcraftstudios.com","availableLanguage":["English"],"areaServed":"Worldwide"}]}</script>
<script type="application/ld+json">{"@context":"https://schema.org","@type":"WebSite","@id":"https://www.zcraftstudios.com/#website","url":"https://www.zcraftstudios.com","name":"ZCraft Studios","alternateName":["ZCS","ZCraft"],"description":"ZCraft Studios (ZCS) creates Minecraft plugins, server configs and tools. Browse resources, compatibility details and setup guides.","inLanguage":"en","publisher":{"@type":"Organization","@id":"https://www.zcraftstudios.com/#organization","name":"ZCraft Studios","url":"https://www.zcraftstudios.com"},"potentialAction":{"@type":"SearchAction","target":{"@type":"EntryPoint","urlTemplate":"https://www.zcraftstudios.com/products?q={search_term_string}"},"query-input":"required name=search_term_string"}}</script>
<script type="application/ld+json">{"@context":"https://schema.org","@type":"BlogPosting","@id":"https://www.zcraftstudios.com/blog/update-paper-plugin-to-minecraft-26-1#article","headline":"Update a Paper Plugin for Minecraft 26.1: Java 25 Guide","url":"https://www.zcraftstudios.com/blog/update-paper-plugin-to-minecraft-26-1","mainEntityOfPage":"https://www.zcraftstudios.com/blog/update-paper-plugin-to-minecraft-26-1","isPartOf":{"@type":"WebSite","@id":"https://www.zcraftstudios.com/#website","name":"ZCraft Studios","url":"https://www.zcraftstudios.com"},"speakable":{"@type":"SpeakableSpecification","cssSelector":["h1","main"]},"description":"Developer guide to updating a Paper plugin to Minecraft 26.1+: Java 25, Paper API versions, api-version, world storage changes and testing.","datePublished":"2026-10-27T04:59:13.441843+00:00","dateModified":"2026-10-27T04:59:29.068351+00:00","author":{"@type":"Organization","@id":"https://www.zcraftstudios.com/#organization","name":"ZCraft Studios","url":"https://www.zcraftstudios.com/about"},"publisher":{"@type":"Organization","@id":"https://www.zcraftstudios.com/#organization","name":"ZCraft Studios","url":"https://www.zcraftstudios.com","logo":{"@type":"ImageObject","url":"https://www.zcraftstudios.com/img/apple-touch-icon.png","width":180,"height":180}},"inLanguage":"en","image":"https://www.zcraftstudios.com/api/og/blog/update-paper-plugin-to-minecraft-26-1?v=1fzjwf1"}</script>
<script type="application/ld+json">{"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https://www.zcraftstudios.com/"},{"@type":"ListItem","position":2,"name":"Blog","item":"https://www.zcraftstudios.com/blog"},{"@type":"ListItem","position":3,"name":"Update a Paper Plugin for Minecraft 26.1: Java 25 Guide","item":"https://www.zcraftstudios.com/blog/update-paper-plugin-to-minecraft-26-1"}]}</script>