UnsupportedClassVersionError

UnsupportedClassVersionError means your class was compiled with a newer JDK than the JRE running it. The JVM refuses to load bytecode newer than its own version.

What It Means

Each Java release produces class files with a specific major version number (e.g., Java 8 = version 52, Java 11 = 55, Java 17 = 61). A JRE can only load class files up to its own version. Running a Java 17 compiled class on a Java 11 JRE triggers this error.

Why It Happens

• You compiled with JDK 17 but run with JRE 8.
• Your IDE uses one JDK version but your terminal java command uses another.
• A library dependency was built with a newer Java version than your runtime.
• Your build server and production server have different JDK versions.
• You have multiple JDKs installed and the wrong one is first on PATH.

How to Fix It

1. Check both versions

# Compile version
javac -version

# Runtime version
java -version

Make sure the major version of java is >= the version of javac.

2. Compile targeting an older version (cross-compilation)

# Compile Java 17 source to run on Java 11
javac --release 11 -sourcepath src -d out src/com/example/Main.java

The --release flag ensures the generated bytecode is compatible with the specified version.

With Maven:

<properties>
    <maven.compiler.source>11</maven.compiler.source>
    <maven.compiler.target>11</maven.compiler.target>
</properties>

With Gradle:

java {
    sourceCompatibility = JavaVersion.VERSION_11
    targetCompatibility = JavaVersion.VERSION_11
}

3. Update your runtime JRE

# On Ubuntu/Debian
sudo apt update
sudo apt install default-jre

# Verify update
java -version

4. Set JAVA_HOME to the correct JDK

# List installed JDKs
ls /usr/lib/jvm/
# Or on macOS
ls /Library/Java/JavaVirtualMachines/

# Point JAVA_HOME to the newest one
export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
export PATH=$JAVA_HOME/bin:$PATH

5. Use a version manager like SDKMAN

# Install SDKMAN
curl -s "https://get.sdkman.io" | bash

# Install and use specific versions
sdk install java 17.0.9-tem
sdk use java 17.0.9-tem