# The server or a plugin needs a newer Java than the server runs

The server software, a plugin or a mod was built for a newer Java version than the one the server runs, so it could not be loaded.

- Code: `java_version_mismatch`
- Severity: fatal
- Category: Java
- Server types: Every server type
- Page: https://failures.perland.online/failures/java_version_mismatch/

## Example log

```text
Minecraft 1.20.5 requires running the server with Java 21 or above. Download Java 21 (or above) from https://adoptium.net/
2026-11-02T18:05:51.117Z  WARN  mc-server-runner  Minecraft server failed. Inspect logs above for errors that indicate cause. DO NOT report this line as an error.  {"exitCode": 1}
```

## Parameters

| Parameter | Meaning |
| --- | --- |
| `requiredJava` | The Java version the code was built for, or the lowest one Paper asks for. |
| `runningJava` | The newest Java version the server's Java can read, which is the Java it runs; present only when Java's own error names it. |

## Log lines this page covers

- `java.lang.UnsupportedClassVersionError: ... has been compiled by a more recent version of the Java Runtime`
- `requires running the server with Java ... or above`
- `Unsupported class file major version`

## What it means

Every Java program is compiled for a Java version, and an older Java cannot run code built for a newer one. Each Minecraft release needs a minimum Java: 1.17 needs Java 16, 1.18 to 1.20.4 need Java 17, and 1.20.5 and later need Java 21. Plugins and mods set their own minimum too.

The diagnosis reads Java's own refusal (`UnsupportedClassVersionError`, which names both versions), Paper's check before the server starts, and the error Paper and CraftBukkit print when a plugin's classes are too new for them to read while they load or convert it. When the server's own code is refused, nothing starts and the issue is fatal. When only a plugin is refused and the server finished starting, the server runs without that plugin and the issue is an error.

## Why it happens

- **The Minecraft version was raised** and the server still runs the Java of the old version.
- **A plugin or mod was built for a newer Java**, often its latest release.
- **The Java version was set by hand** to an older one than the server needs.

## How to fix

1. Find the Java the message asks for: the version it names, or the minimum of your Minecraft version.
2. **Docker (itzg image):** use an image tag with that Java, such as `itzg/minecraft-server:java21`, then start the server again.
3. **Your own host:** install that Java (for example Eclipse Temurin from adoptium.net) and start the server with it. `java -version` shows which Java runs.
4. **Only a plugin or mod needs it:** either move the whole server to the newer Java, or use a release of that plugin or mod built for your current Java.
5. Do not go back to an older Minecraft version to match the Java without a backup of the world first: an older version can damage a world saved by a newer one.

## In Perland

The issue appears in the server's Diagnosis tab with both Java versions when Java names them, and its fix leads to the Java version in the server's Settings. Perland picks the Java of each Minecraft version by itself, so a mismatch usually comes from a Java chosen by hand or a plugin built for a newer Java. The Java version of a network backend cannot be changed from the panel yet.

## References

- [Minecraft Wiki: setting up a server](https://minecraft.wiki/w/Tutorials/Setting_up_a_server)
- [Docker Minecraft Server: Java versions](https://docker-minecraft-server.readthedocs.io/en/latest/versions/java/)
- [Eclipse Temurin (Adoptium) Java downloads](https://adoptium.net/)