Debugging Liferay Gradle Builds When the IDE and CLI Use Different JDKs
The consequences of a version mismatch are one problem. Finding out which tool is using which JDK is a different and surprisingly annoying one, because every tool involved resolves Java independently and most of them do not tell you unless asked directly.
The symptom that starts this is always the same shape: the same command produces different results depending on where it is run. The terminal builds, the IDE does not. Your machine works, the build agent does not. It worked before lunch. None of these are mysteries once you stop assuming there is one Java on the machine.
Ask every tool, separately
Do not infer. Each of these commands answers for one tool only, and the disagreements between them are the entire diagnosis.
# What the shell resolves - often NOT what the build uses
java -version
echo $JAVA_HOME
# The authoritative answer for the build: prints Gradle version,
# the JVM the daemon runs on, and the OS
./gradlew -version
# The Liferay CLI runs on its own resolved JVM
blade version
# And in a workspace, this delegates to the wrapper above
blade gw -versionThe wrapper output is the one that matters for a build, because it reports the JVM the daemon is actually running on rather than the one you configured and hoped for. If that line disagrees with your expectation, everything downstream is explained.
Know the precedence order
The daemon's JVM is chosen by a defined order, and knowing it turns guessing into looking.
| Priority | Source | Notes |
|---|---|---|
| 1 | org.gradle.java.home in gradle.properties | Project file wins; also present in the user-level properties file |
| 2 | JAVA_HOME | The one everybody checks, and the one most often overridden |
| 3 | java on the PATH | The silent fallback when neither of the above is set |
There is a second copy of that properties file in your user home directory, outside the repository. A setting there applies to every project on the machine and is invisible to anyone reviewing the repo - which makes it a common cause of works-on-my-machine that survives a full clean and reclone.
The daemon remembers
The build daemon is a long-lived process started with a specific JVM. Changing a Java setting does not change a daemon that is already running; a compatible one gets reused instead, and your change appears to have done nothing.
# Stop every daemon, then check what a fresh one picks up
./gradlew --stop
./gradlew -version
# Rule out daemon reuse entirely while diagnosing
./gradlew clean build --no-daemonThis single step resolves a large share of cases where a correct configuration change appears to have been ignored. If a fix seems not to work, assume a stale daemon before assuming the fix is wrong.
Why the IDE disagrees
Editors do not use JAVA_HOME for Gradle. Each maintains its own setting for the JVM used to run builds, and it is usually set once at import time from whatever was installed then. It persists through JDK upgrades, so an editor can keep building with a JDK you believe you removed.
- The editor's Gradle integration has an explicit JVM setting, separate from the JDK used for code intelligence.
- Importing a project stores that choice in editor-local files that are not in version control.
- The editor may run its own daemon, so stopping daemons in the terminal does not affect it.
- Language support and the build can use different JDKs simultaneously, which is why errors can appear in the editor but not in a build, or the reverse.
The practical consequence is that fixing the terminal does not fix the editor and vice versa. Fix both, then verify both with the same command.
Read the error for what it says, not what it implies
| Message | What it actually means |
|---|---|
| Unsupported class file major version | The build tool is too old for the JDK it is running on |
| has been compiled by a more recent version of the Java Runtime | Bytecode level is higher than the runtime allows |
| invalid source release | The compiler cannot target that level; the compiling JDK is older than requested |
| Could not determine java version from ... | The build tool cannot parse a newer version string format |
| cannot find symbol on a standard library class | Compiling against an older API than the code was written for |
The reason these cost so much time is that they are all phrased as compilation problems, and the natural response is to open the source file named in the stack trace. In this family of failures the source file is almost never relevant.
A fixed diagnosis routine
- Translate any class file version number in the message into a Java release.
- Run the wrapper version command in the terminal and note the JVM it reports.
- Check both gradle.properties files - the project one and the one in your home directory.
- Open the editor's Gradle JVM setting and compare it with the terminal result.
- Stop all daemons and re-run, to rule out a stale process holding the old JVM.
- Compare all of the above against the portal's runtime Java, which is the version that ultimately constrains everything.
Six checks, each of which takes seconds. Done in order they identify the disagreeing pair immediately, which is the whole problem - the difficulty was never the fix, only knowing which of five Java installations to change.
Remove the class of problem
Diagnosing this repeatedly is a signal that the project is under-specified rather than that the developers are careless. Commit the build JVM setting so the repository declares it, declare the compile JDK through a toolchain so it does not depend on what is installed, pin the same versions in the pipeline, and document the expected combination where a new joiner will see it. A build whose Java version is declared in the repository cannot drift when someone updates their machine or when a build agent image changes underneath the pipeline.
Conclusion
There is no single Java version on a development machine, and treating it as though there were is what makes these failures feel random. The editor, the shell, the build daemon, the command line tooling and the portal each answer the question independently. Ask each of them directly, in a fixed order, translate the error numbers before reading the words around them, and stop the daemon before believing any result. The disagreement is always visible once you look at all five answers side by side.