All posts
CI/CD · 11 min read · May 25, 2026

What Happens When Java Versions Do Not Match Your Liferay Build Toolchain

Java version mismatch across a 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

DecisionWhat it controlsWhere it comes from
The JVM running GradleWhether the build tool itself can start and read classesorg.gradle.java.home, then JAVA_HOME, then PATH
The JDK that compiles your codeWhich language features you can useThe Gradle toolchain setting, or the daemon's JVM by default
The bytecode level producedWhich JVMs can load your classesSource and target compatibility, or the release flag
The JVM running the portalWhether your module loads at runtimeThe application server's own Java configuration
These are independent. Changing one does not move the others.

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 releaseClass file major version
Java 852
Java 1155
Java 1761
Java 2165
Translate the number first; it usually names the culprit immediately.

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.

text
FAILURE: Build failed with an exception.

* What went wrong:
  Could not open init generic class cache for initialization script
  > Unsupported class file major version 61
Nothing here refers to your code, because your code is not the problem.

This 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.

text
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.0
Build-time Java and runtime Java disagreed, and only the runtime noticed.

Bytecode 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.

java
// 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
}
The release option is the one that actually guarantees compatibility.

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

  1. Decide the target Java version from the portal's runtime, not from what is installed locally.
  2. Pin the build JVM in a file that is committed, so every machine and every agent starts from the same place.
  3. Use the release option rather than source and target compatibility alone.
  4. Adopt toolchains so the compile JDK is declared by the project instead of inherited from the environment.
  5. Record the expected versions in the repository README, because the next person will install whatever is current.
  6. 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.

Contact

Let’s connect

Have a Liferay or Backend project you’d like to talk through? Fill in the form and I’ll get back to you.

Book Calendar