How to Fix UnsupportedClassVersionError When Running Keycloak

When launching self-hosted applications like Keycloak, you might encounter specific errors related to your system’s environment. One common issue is the java.lang.UnsupportedClassVersionError, which can halt the startup process. This error indicates a mismatch between the Java version your application was built with and the version installed on your server.

This article walks you through diagnosing and resolving this error, using a real-world example from a user trying to run Keycloak.

The Problem: UnsupportedClassVersionError

After a fresh installation of Keycloak, a user attempts to launch it using the start-dev command:

bashroot@Abhishek:/opt/lampp/htdocs/keycloak-26.3.3# bin/kc.sh start-dev

Instead of starting successfully, the system returns the following error:

textError: LinkageError occurred while loading main class io.quarkus.bootstrap.runner.QuarkusEntryPoint
        java.lang.UnsupportedClassVersionError: io/quarkus/bootstrap/runner/QuarkusEntryPoint 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

This error message is very specific and tells us exactly what is wrong. Let’s break it down.

Understanding the Error

The java.lang.UnsupportedClassVersionError means the Java Virtual Machine (JVM) is trying to load a class file that was compiled with a newer version of Java than the JVM itself supports.

From the error output, we can identify two key pieces of information:

• class file version 61.0: This is the version format of the application’s compiled code (in this case, for Keycloak). This version number corresponds to Java 17.
• class file versions up to 55.0: This is the latest class file version that the currently installed Java runtime can understand. This version number corresponds to Java 11.

The conflict is clear: Keycloak requires Java 17 to run, but the server is using Java 11.

Step-by-Step Solution on Ubuntu

To fix this, you must upgrade the Java environment on your server to a compatible version. Here’s how to install Java 17 and set it as the default on an Ubuntu system.

Step 1: Install Java 17

First, you need to install the OpenJDK 17 package. Open your terminal and run the following commands.

1. Update your package list: This ensures you are getting the latest available packages from the repository. bashsudo apt update
2. Install OpenJDK 17: This command downloads and installs the Java 17 Development Kit (JDK). bashsudo apt install openjdk-17-jdk

Step 2: Set Java 17 as the Default Version

If you have more than one version of Java installed, you must tell the system which one to use by default.

1. Run the update-alternatives command: bashsudo update-alternatives --config java
2. This will display a list of all Java versions installed on your system. You will be prompted to select a version. Enter the number corresponding to the OpenJDK 17 installation and press Enter.

Step 3: Verify the New Java Version

After the installation and configuration are complete, it’s important to verify that your system is now using the correct Java version.

Run the following command:

bashjava -version

The output should now display information indicating you are running OpenJDK version 17.

Step 4: Rerun the Keycloak Script

With Java 17 now active, you can return to your Keycloak directory and run the startup command again.

bashbin/kc.sh start-dev