What Happens When Java Versions Do Not Match Your Liferay Build Toolchain
Installing a newer JDK and watching a Liferay workspace stop building is a rite of passage. The build worked yesterday, nothing in the repository changed, and now a command fails with a message about a class file version number that appears nowhere in your code. The instinct is to suspect the workspace. The cause is almost always that one of several Java versions moved while the others stayed still.
The useful thing to understand is not a list of supported versions - those change with every release and belong in the official compatibility matrix for your Liferay version. It is that a Liferay build makes four separate Java decisions, they are configured in different places, and nothing forces them to agree.
Four Java versions, not one
| Decision | What it controls | Where it comes from |
|---|---|---|
| The JVM running Gradle | Whether the build tool itself can start and read classes | org.gradle.java.home, then JAVA_HOME, then PATH |
| The JDK that compiles your code | Which language features you can use | The Gradle toolchain setting, or the daemon's JVM by default |
| The bytecode level produced | Which JVMs can load your classes | Source and target compatibility, or the release flag |
| The JVM running the portal | Whether your module loads at runtime | The application server's own Java configuration |
Most developers manage the first by setting JAVA_HOME and assume the other three follow. They do not, and the failures each one produces look nothing alike.
Decoding the class file version
Nearly every message in this family mentions a class file version, and the number is not the Java version. The mapping is simple arithmetic - the class file major version is the Java feature release plus forty-four.
| Java release | Class file major version |
|---|---|
| Java 8 | 52 |
| Java 11 | 55 |
| Java 17 | 61 |
| Java 21 | 65 |
Once you can read the number, the error tells you which of the four decisions is out of line. A complaint about version 61 in a project that targets Java 11 means something produced or encountered Java 17 bytecode where Java 11 was expected, and the next question is simply which of the four.
The most common failure: the build tool cannot read its own world
The message that causes the most confusion appears during the build itself, usually before any of your code is compiled.
FAILURE: Build failed with an exception.
* What went wrong:
Could not open init generic class cache for initialization script
> Unsupported class file major version 61This is not a complaint about your modules. It is the build tool saying it cannot parse classes compiled at that level, because the bytecode library inside it predates that Java release. In other words, Gradle is running on a JDK newer than the Gradle version supports. The fix is to either run the build on an older JDK or upgrade the build tool - never to change your project's target level, which is what the message tempts people into doing.
This matters for Liferay specifically because a workspace pins a Gradle wrapper version, and that version was chosen when the workspace was created. A workspace generated a few years ago carries a Gradle version that predates the JDK you just installed, and the mismatch surfaces the first time you run any task at all.
The second failure: bytecode the portal cannot load
This one passes the build cleanly and fails at deployment, which makes it more expensive. The module compiles, the JAR is produced, the bundle installs, and then the portal refuses to use it.
java.lang.UnsupportedClassVersionError: com/example/InvoiceServiceImpl
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.0Bytecode compatibility runs one way only. A newer JVM will happily load older bytecode; an older JVM cannot load newer bytecode under any circumstances. So the rule is that your target level must be no higher than the Java version the portal runs on, regardless of what you develop with.
In an OSGi runtime this also interacts with how packages are wired, because the bundle metadata records the Java version your code requires. A module built for a level the framework cannot provide will not resolve, which presents as a bundle that installs but never becomes usable - a symptom that looks like a dependency problem and is not.
Why source compatibility is not enough
Setting source and target compatibility to an older release is the usual answer, and it is incomplete. Those settings control the language level and the bytecode level, but the compiler still resolves against the class library of whichever JDK is running it. Code that compiles cleanly against a newer library can call a method that does not exist in the older runtime, and nothing fails until production.
// Controls language and bytecode level, but compiles against
// the current JDK's class library.
sourceCompatibility = 11
targetCompatibility = 11
// Compiles against the Java 11 API as well, so calls to newer
// library methods fail at build time rather than at runtime.
tasks.withType(JavaCompile) {
options.release = 11
}Toolchains solve the same problem from the other direction: they let the build run on one JDK while compiling with another, downloading or locating the required JDK rather than depending on whatever the developer happened to install. On a team where everyone has a different machine, this is the single change that removes the most friction.
Why this bites Liferay teams harder
- A workspace pins a Gradle version, so the build tool ages while the developer's JDK does not.
- The command line tooling, the IDE and the build all resolve Java independently.
- The portal's own runtime Java is usually set by whoever installed the server, not by the developer.
- Modules are deployed into a shared runtime, so one wrongly targeted module fails in an environment where everything else works.
- Build agents frequently run a different JDK from every developer machine, so the first failure often appears in the pipeline.
That last point is the one worth designing around. A pipeline that does not pin its Java version is a build that can break because an agent image was updated, with no commit to blame.
Making it stop happening
- Decide the target Java version from the portal's runtime, not from what is installed locally.
- Pin the build JVM in a file that is committed, so every machine and every agent starts from the same place.
- Use the release option rather than source and target compatibility alone.
- Adopt toolchains so the compile JDK is declared by the project instead of inherited from the environment.
- Record the expected versions in the repository README, because the next person will install whatever is current.
- Keep the build tool version and the JDK version moving together; upgrading either alone is what creates the gap.
Conclusion
A Java version mismatch is not really a Java problem. It is four independent configuration decisions that nothing keeps in sync, surfacing through error messages that name a class file number instead of the setting that caused it. Translate the number, identify which of the four decisions moved, and fix that one rather than the one the message points at. When the tools genuinely disagree with each other about which JDK they are using, finding out which is telling the truth is its own short procedure.