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.

The JVM refuses to load a class and tells you exactly why:
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.0Class 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 version | Java release |
|---|---|
| 52 | 8 |
| 55 | 11 |
| 61 | 17 |
| 65 | 21 |
| 69 | 25 |
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
java -version
echo $JAVA_HOME
which java
./mvnw -vThe 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:
<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:
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:
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 2The 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:
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 -5Convert 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:
<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:
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
| Place | What to check |
|---|---|
| Dockerfile | The tag of the base image, eclipse-temurin:21-jre against :17-jre |
| CI job | The setup step, and java -version printed in the log |
| Application server | The JDK the server was started with, not the one on the path |
| Systemd unit or script | JAVA_HOME set in the environment file |
| Cloud runtime | The 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.


