Java "UnsupportedClassVersionError" in CI - Fix the JDK Version Gap

A class file carries a major version stamp for the Java release it was compiled for. UnsupportedClassVersionError fires when the running JVM is older than that stamp - it literally cannot interpret newer bytecode.

What this error means

Startup or a test fails with has been compiled by a more recent version of the Java Runtime (class file version 61.0), this version of the Java Runtime only recognizes class file versions up to 55.0. 61.0 is Java 17; 55.0 is Java 11.

java

Exception in thread "main" java.lang.UnsupportedClassVersionError:
com/example/App has been compiled by a more recent version of the Java Runtime
(class file version 61.0), this version of the Java Runtime only recognizes
class file versions up to 55.0

Common causes

Runtime JDK older than the build JDK

Code compiled with JDK 17 (class file 61) cannot run on a JDK 11 (recognizes up to 55). The version numbers map directly: 52=8, 55=11, 61=17, 65=21.

A dependency jar targets a newer Java

A library compiled for a newer release than your runtime JVM triggers the same error when its classes load.

How to fix it

Run on a JDK at least as new as the build JDK

Provision the matching runtime so it can read the bytecode.

.github/workflows/ci.yml

- uses: actions/setup-java@v4
  with:
    distribution: temurin
    java-version: '17'
- run: java -version   # confirm the runtime is >= the build JDK

Or lower the compiled bytecode target

If you must run on the older JVM, compile down to its level with --release.

pom.xml

<properties>
  <maven.compiler.release>11</maven.compiler.release>
</properties>

How to prevent it

Pin one JDK across build and run with setup-java, and keep --release no higher than the JVM that executes the code.