java.lang.UnsupportedClassVersionError
ID: java/unsupportedclassversionerror
Version Compatibility
| Version | Status | Introduced | Deprecated | Notes |
|---|---|---|---|---|
| 17 | active | — | — | — |
Root Cause
UnsupportedClassVersionError occurs when a class file was compiled with a newer JDK version than the JRE running it. The error message includes class file version numbers (e.g., 61 = JDK 17, 65 = JDK 21).
genericWorkarounds
-
95% success Upgrade the JRE to match or exceed the JDK version used to compile the class files
1. Read the error message: 'class file version 65.0' means JDK 21, '61.0' means JDK 17, '55.0' means JDK 11. 2. Install the matching or newer JDK. 3. Update JAVA_HOME and PATH to point to the new JDK. 4. Verify with 'java -version'. 5. In CI/CD, update the JDK version in the pipeline configuration.
-
88% success Set the build tool to cross-compile to the target JRE's bytecode version
1. In Maven, set <maven.compiler.release>17</maven.compiler.release> in pom.xml to target JDK 17 bytecode. 2. In Gradle, set java { toolchain { languageVersion = JavaLanguageVersion.of(17) } } to compile for JDK 17. 3. This only works for your own code — ensure all dependencies also target the same or lower bytecode version. 4. The --release flag is preferred over -source/-target as it also checks API compatibility.
Dead Ends
Common approaches that don't work:
-
Downgrading the dependency that contains the incompatible class to an older version
50% fail
Downgrading dependencies can introduce security vulnerabilities, missing features, or incompatibilities with other dependencies that require the newer version. It is almost always better to upgrade your runtime JDK than to downgrade libraries.
-
Setting -source and -target compiler flags without upgrading the JRE
70% fail
The -source and -target flags control what your code compiles to, but they do not affect third-party dependencies. If a dependency JAR was compiled with JDK 21 bytecode, your runtime JRE must be >= 21 to load it regardless of your own compilation flags.