Skip to content
javahacks.dev
Java Core

Fix UnsupportedClassVersionError Class File Version Mismatch

Map the class file version in the error to a Java release, then align the runtime, the compiler release flag and the toolchain so the mismatch cannot return.

6 min read
Summarize in AI
Flat illustration of an editor window full of code, with the OpenJDK, Docker and Spring logos.

The JVM refuses to load a class and tells you exactly why:

Text
Exception in thread "main" java.lang.UnsupportedClassVersionError: dev/javahacks/App has been compiled by a more recent version of the Java Runtime (class file version 69.0), this version of the Java Runtime only recognizes class file versions up to 65.0

Class file version 69 was produced by a Java 25 compiler, and the runtime that tried to load it is Java 21. Nothing is corrupted. The two numbers are the whole message.

Decode the numbers

Class file major versionJava release
528
5511
6117
6521
6925

The rule is: major version equals the Java release plus 44. Releases in between follow the same pattern (Java 24 is 68). A runtime can load class files up to its own version and older, never newer.

Find which Java actually runs

Shell
java -version
echo $JAVA_HOME
which java
./mvnw -v

The four commands often disagree. java -version is what the shell runs, JAVA_HOME is what Maven and many tools use and mvnw -v shows the JDK Maven picked. On macOS, /usr/libexec/java_home -V lists the installed JDKs. A server or container that runs your jar may have an older JDK than your laptop: check the base image tag in the Dockerfile and the JAVA_HOME of the service. The cases around that variable are in fixing JAVA_HOME is not defined correctly.

Fix 1: run on a newer JDK

If you control the runtime, upgrade it to the version that compiled the code. For a container, use a matching base image such as eclipse-temurin:25-jre. This is the right answer when you build on a current JDK and deploy to an old one by accident.

Fix 2: compile for the runtime you have

If the runtime is fixed, compile for it. Use the release flag, not source and target:

pom.xmlXML
<properties>
    <maven.compiler.release>21</maven.compiler.release>
</properties>

--release 21 sets the language level, the class file version and the visible API to Java 21, so using a Java 25 method fails at compile time instead of at runtime. source and target alone change the first two and leave the API wide open. Build with JDK 25 or any newer JDK and still produce Java 21 bytecode. The options are explained in invalid target release in Maven.

Fix 3: pin the toolchain

In a team, the problem of a build that works on one laptop returns when the build uses whatever JAVA_HOME points to. A Maven toolchain or Gradle's java.toolchain selects a JDK by version, independent of the environment:

build.gradle.ktskotlin
java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(25)
    }
}

The error from a dependency

If the failing class is not yours, a library was compiled for a newer Java than you run. The stack trace shows its package. Use an older version of the library that supports your runtime, or upgrade the runtime. Libraries publish their minimum Java version in the release notes.

Read the version from a class file

When a jar is the suspect, the class file says what produced it. javap prints the major version:

Shell
javap -v -cp app.jar dev.javahacks.App | grep 'major version'
unzip -p lib/some-library.jar 'dev/example/Foo.class' | xxd -s 6 -l 2

The first prints major version: 69. The second shows the two bytes at offset 6, 0045 for 69. Applying it to the libraries in a failing application finds the one that was built for a newer Java than the runtime offers. Multi-release jars hold extra classes under META-INF/versions/, so a library may be loadable on 17 with its main classes and need 21 only for an optional part.

Check the whole dependency set at once

Searching jars by hand does not scale. A short script over the unpacked lib directory prints the highest class version in each jar:

Shell
for jar in lib/*.jar; do
  v=$(unzip -l "$jar" | awk '/\.class$/ {print $4}' | head -1 | xargs -I{} sh -c "unzip -p $jar {} | xxd -s 6 -l 2 -p")
  echo "$v $jar"
done | sort | tail -5

Convert the hex values with the table: 0034 is Java 8, 003d is 17, 0041 is 21, 0045 is 25. A list ending in a version above your runtime names the jars to replace. The JDK tool jdeps --multi-release 17 --print-module-deps helps too when the question is about modules and API use.

Make the build refuse the mismatch

Finding the error at runtime means a deployed failure. Let Maven check before packaging:

XML
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-enforcer-plugin</artifactId>
    <version>3.5.0</version>
    <executions>
        <execution>
            <goals><goal>enforce</goal></goals>
            <configuration>
                <rules>
                    <requireJavaVersion><version>[21,)</version></requireJavaVersion>
                    <enforceBytecodeVersion>
                        <maxJdkVersion>21</maxJdkVersion>
                    </enforceBytecodeVersion>
                </rules>
            </configuration>
        </execution>
    </executions>
    <dependencies>
        <dependency>
            <groupId>org.codehaus.mojo</groupId>
            <artifactId>extra-enforcer-rules</artifactId>
            <version>1.9.0</version>
        </dependency>
    </dependencies>
</plugin>

enforceBytecodeVersion comes from the extra rules artifact and fails the build when a dependency contains classes newer than the stated maximum. Set the maximum to the Java version of your production runtime, and a library upgrade that raises the requirement fails in CI.

Pin the toolchain in Gradle

In Gradle, a toolchain declares the Java version for compiling and testing, and downloads it if missing:

kotlin
java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(21)
    }
}

The compiler and the test runner then use Java 21 whatever JAVA_HOME says on the machine. The runtime in production still has to be 21 or later, so the Docker base image tag is part of the same decision.

Where the runtime version hides

PlaceWhat to check
DockerfileThe tag of the base image, eclipse-temurin:21-jre against :17-jre
CI jobThe setup step, and java -version printed in the log
Application serverThe JDK the server was started with, not the one on the path
Systemd unit or scriptJAVA_HOME set in the environment file
Cloud runtimeThe runtime setting in the platform configuration

The server row causes the most trouble. A developer upgrades the JDK on a laptop, builds a jar for 21, and the application server on the test host starts with an older one it was installed with years ago. Print System.getProperty("java.version") at startup in the log, and the question answers itself.

Decide the target once for the whole organisation

Version mismatches come from teams choosing different Java versions without telling each other. A shared rule helps: libraries target the oldest Java version that any consumer still runs, and applications run on the newest long-term support release that the platform team supports. A library compiled with --release 17 runs on 17, 21 and 25, while one compiled for 25 runs only on 25.

Publish the rule in the engineering handbook, and enforce it with the enforcer rule shown above. Raising a library's target is a breaking change for consumers on older runtimes, so announce it as one and change the major version.

Where this does not apply

If the error mentions a module or --enable-preview, you are loading a class compiled with preview features, which must run on the same release with the flag. For classpath problems that are not version related, see ClassNotFoundException and NoClassDefFoundError. The Maven compiler plugin documentation covers the release option. The JVM specification's class file format chapter defines the version numbers, and the modern Java guide covers what each release adds.

Also inDevOps
Share

Keep reading

Get new posts by email

We send one email when a new post is published. No spam.

Unsubscribe in one click. No spam, ever.