Which Java Version Does Your Minecraft Server Need? (Complete Guide)

Your server was running fine yesterday. Today you updated to Paper 26.1.2, clicked Start, and got hit with Unsupported class file major version 69. No stack trace, no helpful error message — just a dead server and a cryptic number.

That number is how Minecraft tells you your Java version is wrong. And if you've ever wondered whether you can just install the newest Java and be done with it, the answer is: almost, but not quite. Java versions and Minecraft versions are locked together, and running the wrong combination causes silent failures, memory leaks, or outright crashes.

This guide covers everything a server admin needs to know: the compatibility matrix, how to check your current version, what common errors mean, and how to pick the right garbage collector for your server size.

The Minecraft-Java Compatibility Matrix

Minecraft's Java requirements have escalated over the past few years. Each major Minecraft release bumps the minimum Java version, and running below that minimum means your server won't start.

A few clarifications:

"Minimum" vs. "Recommended": The minimum is what Mojang guarantees will work. Running a newer Java version often improves garbage collection and memory efficiency, but occasionally breaks mods compiled for older bytecode. If you're running a vanilla or Paper server, use the recommended version. If you're running a heavily modded Forge server, check whether your mods explicitly support newer Java.

Why does Minecraft keep requiring newer Java? Mojang takes advantage of language features and runtime improvements in newer releases. Java 21 introduced virtual threads and better GC defaults. Java 25 brought significant ZGC improvements that Minecraft 26.1 leverages for large worlds. The upgrade is not arbitrary — it's how the game gets faster without you changing your hardware.

What about Java 26? Java 26 is out, but Minecraft 26.1.2 does not officially support it yet. Some admins run it successfully; others report subtle entity-tick issues. If you're adventurous, test it on a staging server first. The safer choice is Java 25 until Mojang confirms compatibility. This was the topic of a recent discussion on r/admincraft — the consensus is "it works, mostly, but don't run it in production without testing."

How to Check Your Server's Java Version

Before troubleshooting any crash, confirm what Java your server is actually running. This sounds obvious, but many hosts install multiple Java versions, and your server might be picking up the wrong one.

From the Server Console

The cleanest method: start your server and look at the first few lines of output. Minecraft logs the Java version on startup:

[06:00:01] [main/INFO]: Environment: Environment[sessionHost=https://sessionserver.mojang.com, ...
[06:00:01] [main/INFO]: Java: 25.0.1, Oracle Corporation

If you see Java: 17.0.x when you expected 25, your startup script is pointing at the wrong binary.

From the Command Line

If you have SSH or terminal access to your server, run:

java -version

This shows the default Java on the system PATH. Output looks like:

openjdk version "25.0.1" 2026-03-18
OpenJDK Runtime Environment (build 25.0.1+9)
OpenJDK 64-Bit Server VM (build 25.0.1+9, mixed mode, sharing)

If this doesn't match what you expected, your system has multiple Java installations and your startup script may be using a different one. Check your start.sh or systemd unit for an explicit path like /usr/lib/jvm/java-25-openjdk/bin/java.

On Managed Hosting

If you're on Swelis or another managed host, you typically don't need to worry about Java version management. Swelis provisions Java 25 automatically and updates it when upstream releases arrive. The panel handles the plumbing so you don't have to SSH in and wrangle symlinks.

That said, if you're debugging a crash and the console shows a Java version you didn't expect, contact your host's support — the provisioning might have a stale image.

Common Errors and What They Mean

Java version mismatches produce specific errors. Here's how to decode them.

"Unsupported class file major version X"

This is the most common mismatch error. The number X maps to a Java version:

If you see Unsupported class file major version 69, your server JAR was compiled for Java 25, but you're running an older Java. Upgrade your Java installation.

If you see Unsupported class file major version 65 on a 1.18 server, you probably installed a plugin compiled for Java 21 while running Java 17. Either upgrade Java or find a Java 17 build of the plugin.

"A JNI error has occurred, please check your installation"

This usually means Java itself is misconfigured — often caused by mixing 32-bit and 64-bit installations, or by a corrupted JDK. Reinstall Java cleanly.

"Error: LinkageError occurred while loading main class"

Similar to the JNI error. Typically means your startup command references a Java version that doesn't exist, or there's a conflict between multiple Java installations. Check that your java binary path is correct.

"Could not reserve enough space for object heap"

This isn't a version mismatch — it's a memory allocation failure. Your JVM arguments request more RAM than the OS can provide. Reduce your -Xmx value, or check if another process is hogging memory. See our RAM guide for sizing recommendations.

Server starts, but crashes later with NullPointerException in entity ticks

This is the sneaky one. Some Java versions have subtle runtime differences that cause rare crashes under load. If you're running a Java version ahead of Mojang's official support (e.g., Java 26 on Minecraft 26.1.2), this is a warning sign. Roll back to the officially supported version and test again.

GC Options: G1GC vs. ZGC for Different Server Sizes

Picking the right Java version is half the battle. The other half is configuring the garbage collector. The GC is responsible for cleaning up unused memory — and if it pauses too long, your server stutters.

What Is GC Pause?

When the JVM runs garbage collection, it briefly pauses the server. Short pauses (under 20ms) are invisible. Long pauses (over 100ms) cause visible lag — entities freeze, blocks don't break, players rubberband.

G1GC: The Workhorse Default

G1GC (Garbage-First Garbage Collector) has been the Minecraft community's standard for years. It balances throughput and pause times, and it works well on servers with 2–16 GB of RAM.

Recommended G1GC flags for most servers:

-XX:+UseG1GC
-XX:MaxGCPauseMillis=100
-XX:G1HeapRegionSize=16M
-XX:+ParallelRefProcEnabled
-XX:+UnlockExperimentalVMOptions
-XX:+DisableExplicitGC

The MaxGCPauseMillis=100 tells G1GC to aim for sub-100ms pauses. It won't always hit that target, but it prioritizes latency over raw throughput.

ZGC: For Large Servers and High RAM

ZGC (Z Garbage Collector) is a low-latency collector designed for large heaps. It keeps pause times under 1ms regardless of heap size — a major upgrade if you're running 16 GB or more.

Java 25 shipped significant ZGC improvements, and Minecraft 26.1 officially recommends ZGC for servers with 8+ GB RAM. The 26.1.2 admin guide covers this in depth.

Basic ZGC flags:

-XX:+UseZGC
-XX:+ZGenerational
-XX:SoftMaxHeapSize=12G

ZGenerational enables the generational mode introduced in Java 21, which improves throughput for long-running processes. SoftMaxHeapSize sets a target heap size that ZGC tries not to exceed, while still allowing bursts.

When to Use Which

If you're running a small server and don't want to think about it, stick with G1GC. If you're experiencing GC-related lag spikes on a larger server, ZGC is worth the switch.

A Note on Shenandoah

Shenandoah is another low-latency collector, available in some OpenJDK builds. It's comparable to ZGC for many workloads. However, it's not included in Oracle JDK builds, and the Minecraft community has less collective experience tuning it. If you're on a Red Hat-based system with Shenandoah available, it's a valid option — but ZGC is the safer default in 2026.

Putting It Together: A Version-Upgrade Checklist

When Minecraft releases a new version that requires a newer Java, here's the cleanest upgrade path:

1. Check the requirements. Look up the new Minecraft version's minimum Java. Don't assume.

2. Test on a staging server. Copy your world to a test instance, upgrade Java, start the server, and join. Walk around, open chests, trigger redstone. Look for errors in the console.

3. Check your plugins. Some plugins are compiled for specific Java versions. If a plugin hasn't been updated, it might crash on newer Java. Check the plugin's download page or Spigot/Paper thread for compatibility notes.

4. Update your startup script. If you specify a Java path explicitly (e.g., /usr/lib/jvm/java-21-openjdk/bin/java), update it to the new version. If you rely on system PATH, make sure the new Java is the default.

5. Adjust GC flags if needed. If you're crossing the ZGC threshold (e.g., upgrading from Java 17 to Java 25 on a large server), consider switching from G1GC to ZGC.

6. Monitor the first few days. Watch for unusual memory growth, GC pauses, or crash logs. The server lag troubleshooting guide covers common post-upgrade issues.

If you're on a managed platform like Swelis, steps 2–4 are handled for you — the platform provisions the correct Java version when you select a Minecraft version from the control panel. You still want to test your plugins, but the infrastructure side is automated.

Quick Reference

Related Guides

• Minecraft 26.1.2 Is Out: What Server Admins Need to Know — Full breakdown of Java 25 requirements, the new 4 GB default, and the security fix that shipped with 26.1.2.
• How to Fix Minecraft Server Lag (The Complete Guide) — If Java is right but your server still stutters, the problem is elsewhere. This guide covers entities, view distance, plugins, and more.
• Paper, Purpur, Fabric, or Forge? — Choosing server software affects your Java requirements too. Forge mods especially can be picky about versions.
• Minecraft Server Hosting: What RAM Do I Need? — RAM and Java version go hand in hand. More RAM enables ZGC; too little RAM causes OOM crashes regardless of Java.
• How to Set Up Your First Minecraft Server in Under 2 Minutes — New to server hosting? Start here. Java version is handled automatically on Swelis.
• Minecraft server.properties Explained — Once Java is sorted, tune your server settings. Every option in server.properties, explained.