Skip to main content
The Java version used by the Minecraft server is determined by the Docker image tag you choose. Different Minecraft versions require different Java versions to run properly.

​
Image Tags

Image references can either omit the tag (which defaults to latest) or explicitly specify a tag: 
# Using default 'latest' tag (Java 25)
itzg/minecraft-server

# Using explicit tag
itzg/minecraft-server:java21

​
Available Java Versions

TagJava VersionLinuxJVM TypeArchitectureNotes
latest25UbuntuHotspotamd64, arm64Default
stable25UbuntuHotspotamd64, arm64Most recent release
java2525UbuntuHotspotamd64, arm64
java25-jdk25UbuntuHotspot+JDKamd64, arm64
java25-graalvm25OracleOracle GraalVMamd64, arm64
java2121UbuntuHotspotamd64, arm64
java21-jdk21UbuntuHotspot+JDKamd64, arm64
java21-alpine21AlpineHotspotamd64, arm64
java21-graalvm21OracleOracle GraalVMamd64, arm64
java1717UbuntuHotspotamd64, arm64, armv7
java17-graalvm17OracleOracle GraalVMamd64, arm64
java1111UbuntuHotspotamd64, arm64, armv7
java88UbuntuHotspotamd64, arm64, armv7
The latest tag shifts to include not only the latest features and bug fixes, but also the latest Java version that Mojang requires for the latest Minecraft version.

​
Usage Examples

docker run -it -e EULA=TRUE itzg/minecraft-server:java8

​
Version Compatibility

Refer to the Minecraft Wiki’s Java update guide for the required Java version for each vanilla Minecraft version.

​
Common Compatibility Issues

​
Class File Version 65.0

If you encounter this error, you need Java 21 or later: 
Exception in thread "ServerMain" java.lang.UnsupportedClassVersionError: 
org/bukkit/craftbukkit/Main has been compiled by a more recent version of 
the Java Runtime (class file version 65.0)
Ensure you have pulled the latest image or explicitly use the java21 tag.
Solution: 
# Re-pull the latest image
docker pull itzg/minecraft-server:java21

# Or use explicit tag
docker run -d -e EULA=TRUE itzg/minecraft-server:java21

​
Forge Compatibility Issues

Forge and its mods sometimes use non-public Java APIs and can break with newer Java versions. Java 21 Issues: Some mods for Minecraft 1.21 require Java 17. If you see: 
Caused by: org.spongepowered.asm.mixin.throwables.ClassMetadataNotFoundException: java.util.List
Use the Java 17 image: 
services:
  mc:
    image: itzg/minecraft-server:java17
Java 8 Required: For Forge versions less than 1.18, you must use java8: 
Caused by: java.lang.ClassCastException: class jdk.internal.loader.ClassLoaders$AppClassLoader 
   cannot be cast to class java.net.URLClassLoader
Solution: 
docker run -d -e EULA=TRUE itzg/minecraft-server:java8
Forge does not support the OpenJ9 JVM implementation.

​
Release Versions

You can pin a specific build of the image using release tags: 
itzg/minecraft-server:<release>-<java-tag>
Example: 
# Pin to the 2024.4.0 release with Java 17
docker run -d itzg/minecraft-server:2024.4.0-java17
See GitHub releases for available versions.

​
Stable Image Tag

The stable tag combines benefits of latest and release versions: 
# Always uses the most recently released version
docker run -d itzg/minecraft-server:stable

# Per-variant stable tags
docker run -d itzg/minecraft-server:stable-java17

​
GraalVM Images

GraalVM images are based on Oracle GraalVM and use the GraalVM Free License.
GraalVM images use Oracle Linux (based on RHEL). The Forge Installer will not work due to zlib-ng compatibility issues. Use standard images for initial Forge installation and version upgrades.

​
Alpine Images

Alpine-based images provide a smaller footprint: 
docker run -d itzg/minecraft-server:java21-alpine
Alpine images for Java 17 do not include arm64 architecture because the base Eclipse Temurin images don’t provide that combination. Use Ubuntu-based images instead.

​
Troubleshooting

​
Class File Version Errors

If you see “class file version” errors, refer to the Java bytecode version table to identify the required JDK version.
Class File VersionJava Version
65.0Java 21
61.0Java 17
55.0Java 11
52.0Java 8

​
Programmatic Access

Image tag information is available in JSON format: 
curl https://raw.githubusercontent.com/itzg/docker-minecraft-server/refs/heads/master/images.json

Build docs developers (and LLMs) love

Get started for freeTalk to us