How to Handle “class file has wrong version” Errors in Java

1. Overview

While working with Java projects, a common error when setting up a new project or updating or adding a dependency is the “class file has wrong version” error.

In this tutorial, we’ll look at why this error occurs and explore two solutions.

2. Cause

To understand the root cause, we need to know more about class files.

Whenever we compile Java code, a .class file is created for each class contained in the files being compiled. Part of the metadata for these .class files is a version number that corresponds with the current major version number of Java used to compile the code.

For the most common Java versions, these class version numbers are 65.0 for Java 21, 61.0 for Java 17, 55.0 for Java 11, and 51.0 for Java 8. If we’re using a different version of Java, we can add or subtract one as needed to figure out the corresponding class file version number.

At runtime, Java looks at each .class file and requires that the version number for the runtime environment is greater than or equal to the version number used to compile the .class file. This version number requirement is due to Java’s backward compatibility mechanics. That means if we’re running code using Java 17, we can use any class files compiled with Java 17 or a previous version of Java. But if we come across a .class file compiled with Java 21, then we’ll encounter the error “class file has wrong version 65.0, should be 61.0”.

3. Solutions

As we’ve just learned, the “class file has wrong version” error is caused by using code compiled with a higher version of Java than the version used at runtime.

3.1. Upgrading Java

The first solution we’ll explore is upgrading our runtime environment. The first step would be to download and install an upgraded version of Java. The steps for installing and upgrading Java could vary for Windows, macOS, and Ubuntu.

Suppose we encounter the error “class file has wrong version 61.0 (Java 17), should be 55.0 (Java 11)”. Then, we can fix this by installing a version of Java 17+ and updating the build property that manages the Java compiler version. If using Maven, we simply update the pom.xml file:

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

3.2. Downgrading Dependency

In some cases, we may not have the option to upgrade the Java environment. For this, we’ll need to diagnose which dependency is creating the error.

Using Spring dependencies as an example, the current major release versions are Spring Framework 6 and Spring Boot 3. Both require at least Java 17, but Spring Framework 5 and Spring Boot 2 are compiled with Java 8.

This means that if we’re using an older version of Java, we can decrease the Spring dependency to continue running. However, it should be noted that open-source support for these older versions of Spring has ended.

Also, when a dependency is downgraded, we may run into other compilation or runtime errors. This is especially true if newer features of a library are being used, as they may not be available in older versions. In particular, downgrading Spring Framework or Spring Boot may require significant effort.

4. Conclusion

We now have two ways to fix the “class file has wrong version” error.

Downgrading a dependency can often be a quicker fix. However, we run into the potential of using a version that doesn’t have the most recent security patches or support. This can also introduce compilation or runtime errors as the library may have significant changes to revert to an earlier version.

On the other hand, upgrading the Java build and runtime environment allows us to use the most up-to-date dependencies, but this may not be an available solution due to business constraints.