On occasion users may observe a java.lang.UnsupportedClassVersionError exception. The full message would look like so:

java.lang.UnsupportedClassVersionError: <classname> has been compiled by a more recent version of the Java Runtime

This exception message indicates the class attempting to execute is not compatible with the version of the running Java Runtime Environment (JRE). This document explains how to identify the version of Java the classes or JAR files were built with and provide possible solutions.

Why this happens

This situation most commonly occurs when upgrading major versions of the Neo4j database that require a newer version of the Java run-time environment (JRE). The exception could likely occur when loading a custom-built procedure, or using a connector or other program running within the same Java Virtual Machine (JVM) as the database.

Java class files contain a "class file version" number that identifies which JRE version they are compatible with. Each major Java release increments this version number. When you attempt to run a class file with a newer version number than your JRE supports, the JVM throws this error as a safety mechanism. The following table discloses the major version number of the most command and more recent JREs. Other versions can be determined by interpolating values between the listed versions.

Java Version	Major Version	Neo4j Version(s)s
22	66
21	65	2025.01 + (optional for 5.14 - 5.26 LTS)
17	61	5.x
11	55	4.x
8	52	3.x

 

Evidence of this exception will be present in either the Neo4j logs (when loading custom procedures), or application logs when using a connector or other program. The complete exception message will include the major version the class in error requires and the major version supported by the JVM. The version of JRE can be determined from the table above.

Other Possible Scenarios

1. Development environment mismatch: Code was compiled on a machine with a newer Java version than the one used for execution.
2. Dependency conflicts: Third-party libraries compiled with newer Java versions than your runtime.
3. JRE configuration issues: There are multiple Java installed, and an older version is being used.

What to do

All programs or applications running within a given JVM must be compiled using a version of Java compatible with the JRE they are executed within. The version of Java needed by the version of Neo4j should be the determining factor for compatibility. If you experience this exception, it is clear an incompatibility exists, but good planning can mitigate this exception by verifying compatibility prior to performing an upgrade.

When planning an upgrade to the Neo4j database you should verify the required version of Java needed by the new version. This likely occurs when upgrading major versions of Neo4j (e.g., 4.4.x -> 5.x -> 2025.x). To avoid the possibility of this exception, It is necessary to verify the version of Java used to build plugins and any other programs that run within the same JVM as Neo4j. Neo4j distributions include compatible versions of Neo4j-built add-ons (such as APOC Core, Bloom, GenAI and GDS), so it is important to use those versions instead of versions from previous installs.

More importantly, it is necessary to verify and obtain or recompile any 3rd-party plugins or custom procedures before deploying.

How to Diagnose

1. Check your Java runtime version

java -version

2. Determine the class file version

You can use the javap tool to inspect the class file version:

javap -verbose | grep "major version"

Alternatively, you can use the Linux hexdump command:

hexdump -s 7 -n 1 -e '"%d\n"' 

JAR files

Using Manifest file

unzip -p  META-INF/MANIFEST.MF | egrep "(Build-Jdk:|Created)"

Using hexdump

unzip -p YourJARFile  | hexdump -s 7 -n 1 -e '"%d\n"'

For example, executing the following command,

unzip -p neo4j-java-driver-5.8.0.jar org/neo4j/driver/AccessMode.class | hexdump -s 7 -n 1 -e '"%d\n"'

will return the value '61'. Looking up the major version of 61 within the table above tells us this jar file was compiled using Java version 17.

Solutions

3rd-Party plugins: Using the table shown early in this article, obtain an appropriate version for any 3rd-party plugin needing to run in the same JVM as Neo4j that is compatible with the required version of Java used by Neo4j.

Custom Procedures: Recompile

If you have access to the source code, you can recompile it targeting the Java version compatible with the version of Neo4j.

javac -source 11 -target 17 

For Maven projects, add this to your pom.xml:

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