Two different Java errors often show up together after a JDK change. Unsupported class file major version (or UnsupportedClassVersionError) means a program met a .class file newer than it understands. Cannot find symbol is a compiler error. It means the compiler could not find a name you used.
This guide was written for Gradle 8.14, Spring Framework 6.1, JaCoCo 0.8.12 and Mockito 5.17, with the Java versions from the Gradle compatibility matrix. Causes are listed from most to least likely, each with a fix and a check.
Read the error before you change anything
Every .class file stores the Java version it was compiled for as a major version. A JVM loads class files up to its own version and never a newer one. Class files are backward compatible, but not forward compatible.
Use this table of the versions that matter most here:
| Java version | Class file major version |
|---|---|
| 8 | 52 |
| 11 | 55 |
| 17 | 61 |
| 21 | 65 |
| 24 | 68 |
| 25 | 69 |
Now find the two numbers in your message. In class file version 69.0 ... only recognizes class file versions up to 65.0, the first is the class (Java 25) and the second is the highest version the running JVM accepts (Java 21). This tells you the class is newer than the runtime.
Then find out who printed the message. The JVM throws UnsupportedClassVersionError. Build tools and frameworks read class files with the ASM library and report Unsupported class file major version 69. The reporter decides the fix, as the next sections show.
Cause 1: You compiled with a newer JDK than the one that runs the app
This is the most common case. You build on JDK 25 and start the app on a JDK 21 server or Docker image. The JVM prints UnsupportedClassVersionError and the launcher adds a LinkageError line for the main class.
Fix: compile for the oldest JDK the app has to run on. Pass --release to javac, because it sets the class file version and also limits the APIs to that Java version.
The example below compiles on JDK 25, fails on JDK 21, then works after --release 21. Create a Hello.java first, any class with a main method.
In Gradle, set options.release on every compile task. This makes the build repeat the fix on every machine, not just yours.
As an alternative, run the app on JDK 25 or newer. The JVM then accepts version 69.
Confirm: run the same java command on the older JDK again. The error must be gone and your program must print its normal output.
javac -d out Hello.java # JDK 25: Hello.class gets major version 69
java -cp out Hello # JDK 21: UnsupportedClassVersionError ... up to 65.0
javac --release 21 -d out Hello.java # JDK 25: Hello.class gets major version 65
java -cp out Hello # JDK 21: Hello runs
tasks.withType<JavaCompile>().configureEach {
options.release = 21
}
tasks.withType(JavaCompile).configureEach {
options.release = 21
}
Cause 2: Your Gradle version is too old for your JDK
Here the JVM is new enough, but the tool is not. Gradle 8.14 runs on Java up to 24 according to the Gradle compatibility matrix. If you run it on JDK 25, the Groovy and ASM versions inside Gradle cannot read the JDK's own class files. The build fails before the first task:
BUG! exception in phase 'semantic analysis' in source unit '_BuildScript_' Unsupported class file major version 69
Compiling your code with --release 21 does not help here. Gradle fails on the JDK's classes, not on yours.
Pick one fix:
- Upgrade Gradle. The matrix lists Java 25 for running Gradle from 9.1.0. Change the version in your Gradle wrapper settings. The matrix also lists Java 26 from 9.4.0 and Java 27 from 9.8.0.
- Run Gradle on a supported JDK and compile with a toolchain. Gradle 8.14 needs a JVM between 8 and 24 here, and toolchains let it compile with another Java version. Set the toolchain as shown below. In the matrix, Java 24 toolchain support starts at Gradle 8.14, and Java 25 starts at 9.1.0.
The Gradle build file below declares a toolchain. It protects the project from being built with different Java versions on different machines.
Confirm: run ./gradlew compileJava. The BUG! exception message must be gone and the task must finish without errors.
java {
toolchain {
languageVersion = JavaLanguageVersion.of(17)
}
}
java {
toolchain {
languageVersion = JavaLanguageVersion.of(17)
}
}
./gradlew compileJava
Cause 3: A library that reads bytecode is older than your classes
Some tools parse .class files themselves. Spring Framework 6.1 scans packages for @Component classes with its own copy of ASM. JaCoCo 0.8.12 and Mockito 5.17 also read bytecode. When they meet major version 69, they fail with a message such as:
ASM ClassReader failed to parse class file - probably due to a new Java class file version that is not supported yet.
Spring also names a system property, spring.classformat.ignore, that skips such files during scanning. Do not use it as a first fix. It hides classes from the scan, so beans may go missing.
Fix, in this order:
- Compile with
--releaseset to a version the library knows, as in Cause 1. This lowers the class version of your own classes. - Upgrade the library to a release that supports your Java version. Check the release notes of Spring, JaCoCo or Mockito. This guide does not list which release adds support for Java 25.
If the failing class comes from a dependency JAR, the app starts and fails later, on the first line that uses it. In that case, upgrade that dependency or run on a newer JVM.
Confirm: run the failing step again, for example the tests or the Spring startup. The ASM message must not appear.
Cause 4: Your IDE, JAVA_HOME and build use different JDKs
Sometimes the build is fine in the terminal and fails in the IDE, or the reverse. Gradle can pick its JDK from several places: the toolchain setting, JAVA_HOME, and the IDE's own Gradle JVM setting.
Two documented rules help you here:
JAVA_HOMEapplies to every Java tool on the machine. It cannot give different projects different JDKs, and it does not override a toolchain.- An IDE setting changes the JVM that runs Gradle. It does not change how your code is compiled, unless your build declares no toolchain.
Fix: declare a toolchain in the build file, as in Cause 2. Then set the IDE's Gradle JVM to a JDK that your Gradle version supports. Look for the setting in your IDE's Gradle options, because the menu name varies by version.
If you use JAVA_HOME, point it at one JDK on purpose:
Confirm: run the build from the terminal and from the IDE. Both must give the same result.
export JAVA_HOME=/path/to/java17
Cannot find symbol: what to check
The Gradle pages do not describe the cannot find symbol message, so this section only lists documented things that change what the compiler can see. For the exact meaning of the message, see the Java compiler documentation of your JDK.
Read the message first. It names the missing symbol and the line of your code. Then check these in order:
- A newer API with a lower
--release. The--releaseflag prevents use of APIs that are not in the chosen Java version. If you setoptions.release = 8and call a newer method, the compiler can no longer see it. Raise the release, or use an API from that version. - A missing dependency. Each source set has its own compile classpath, built from Gradle configurations such as
implementationandcompileOnly. Add the library to the right configuration. - A file in the wrong place. The
compileJavatask compiles files undersrc/main/java, andcompileTestJavacompilessrc/test/java. Move the file there. - A different JDK than you expect. Fix it with a toolchain, as in Cause 2.
A typo in a name, a missing import or a wrong letter case also causes this error. Check them before changing the build.
Confirm: run ./gradlew compileJava again. The task must finish without a compile error.
Troubleshooting
| Problem | Likely cause | Fix |
|---|---|---|
| Gradle fails with Unsupported class file major version 69 before any task runs | Gradle 8.14 runs on a JDK newer than it supports (Java 25), so its Groovy and ASM cannot read the JDK classes. | Upgrade Gradle to 9.1.0 or newer, or run Gradle on a supported JDK and set a toolchain for compilation. |
| UnsupportedClassVersionError with class file version 69.0 and up to 65.0 when the app starts | The classes were compiled on JDK 25 and run on JDK 21. | Compile with --release 21 or set options.release = 21, or run the app on JDK 25 or newer. |
| Spring reports ASM ClassReader failed to parse class file | Spring Framework 6.1 does not recognise the class file version of your classes. | Compile for a lower release, or upgrade Spring. Avoid spring.classformat.ignore as a first fix, because it skips classes during scanning. |
| The build works in the terminal but fails in the IDE | The IDE runs Gradle with a different JVM than JAVA_HOME and no toolchain is declared. | Declare a toolchain in the build file and set the IDE's Gradle JVM to a supported JDK. |
| Cannot find symbol after setting options.release = 8 | The code uses an API that does not exist in Java 8. | Raise the release value or replace the call with an API available in the chosen version. |
Frequently asked questions
What does major version 69 mean?
It is the class file version of Java 25. A JVM or library that understands only older class files rejects it.
Can a newer JVM run older class files?
Yes. Class files are backward compatible, so a JVM loads files up to its own version. It never loads a newer one.
Does compiling with --release 21 fix a Gradle build that fails on JDK 25?
No. In that case Gradle fails on the JDK's own classes, not on yours. Upgrade Gradle to 9.1.0 or newer, or run it on a supported JDK.
Is JAVA_HOME enough to pick the Java version for a project?
It sets a default for all Java tools on the machine, but it cannot set different versions per project and does not override toolchains. A toolchain is more reliable.
References
From Grokem: https://www.grokem.com/programming/fix-unsupported-class-file-major-version-69-and-cannot-find-symbol-in-java-builds








