Skip to content

Fix confusing build failure when javac is missing - #151

Merged
tuhaihe merged 3 commits into
apache:mainfrom
tuhaihe:fix-jdk-preflight-check
Sep 10, 2026
Merged

Fix confusing build failure when javac is missing#151
tuhaihe merged 3 commits into
apache:mainfrom
tuhaihe:fix-jdk-preflight-check

Conversation

@tuhaihe

@tuhaihe tuhaihe commented Sep 9, 2026

Copy link
Copy Markdown
Member

Fixes #150.

Building PXF on a machine that has a JRE but no JDK fails at
:pxf-api:compileJava with a message that never mentions a JDK:

> Error while evaluating property 'javaCompiler' of task ':pxf-api:compileJava'.
   > Toolchain installation '/usr/lib/jvm/java-11-openjdk-amd64' does not
     provide the required capabilities: [JAVA_COMPILER]

Two things then make it hard to get out of:

  1. On Debian/Ubuntu the JRE is installed into /usr/lib/jvm/java-11-openjdk-amd64,
    the same directory a JDK would use, so java -version and ls /usr/lib/jvm
    both look healthy while javac is absent. Gradle's error names that very
    directory, reinforcing the impression that Java is fine there.
  2. Installing the JDK afterwards does not help by itself. server/gradle.properties
    enables the Gradle daemon, and the daemon caches JVM installation metadata for
    its whole lifetime without re-checking the filesystem. Since the JDK lands in
    the same path, Gradle reuses the existing daemon and replays the stale
    verdict -- the identical error, in 2 seconds. ./gradlew --stop is required.

Changes

server/Makefile -- new check-jdk target, hung off prepare-gradle-wrapper
(the chokepoint every Gradle target already depends on). It verifies
$JAVA_HOME/bin/javac, or javac on PATH when JAVA_HOME is unset, and fails
with:

ERROR: no Java compiler (javac) found -- a JDK is required to build PXF, a JRE is not enough.
       JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64 has no bin/javac, so it points at a JRE.
       Install a JDK and point JAVA_HOME at it, for example:
         Debian/Ubuntu: sudo apt-get install -y openjdk-11-jdk
         RHEL/Rocky:    sudo dnf install -y java-11-openjdk-devel
         export JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64
       Then run './gradlew --stop', because a Gradle daemon started
       before the JDK was installed caches the old JVM metadata and
       keeps reporting the same error.

README.md -- state that a JRE is not enough and give the apt/dnf package
names; note that on Debian/Ubuntu the maven package depends on
default-jre-headless and does not pull in a JDK; document the ./gradlew --stop
requirement; update the supported versions from "JDK 1.8 or JDK 11" to 8, 11, 17
and 21, which is what the java-compatibility-test matrix in pxf-ci.yml already
runs, and note that 1.8 support will be removed in PXF 3.0; sync the IntelliJ
section, which also said 1.8. Finally, fix the example JAVA_HOME
(/usr/lib/jvm/java-11-openjdk) -- a RHEL-style path that does not exist on
Debian/Ubuntu, where it needs the -amd64 suffix.

No production code and no Gradle build logic is touched. CI is unaffected:
ci/docker/pxf-cbdb-dev/common/script/build_pxf.sh already installs a JDK
explicitly, which is why this only ever hit people following the README.

Testing

check-jdk was exercised in three states: JAVA_HOME pointing at a JRE-shaped
directory (exit 2 with the message above), JAVA_HOME unset with no javac on
PATH (exit 2), and JAVA_HOME pointing at a real JDK (exit 0). make -n compile
confirms the check runs before Gradle.

The underlying failure was reproduced end to end in a clean ubuntu:22.04
container against the 2.2.0-incubating-rc1 tree:

Phase Environment Result
1 openjdk-11-jre-headless only the [JAVA_COMPILER] error above
2 openjdk-11-jdk installed, daemon not stopped identical error, BUILD FAILED in 2s
3 same, after ./gradlew --stop BUILD SUCCESSFUL in 23s

A clean Ubuntu 22.04 that installs openjdk-11-jdk before the first build succeeds
outright.

The server module needs javac, but Gradle starts happily on a JRE and
only fails later at :pxf-api:compileJava with "Toolchain installation
... does not provide the required capabilities: [JAVA_COMPILER]", which
never mentions a JDK. Check for javac before invoking Gradle so the
build stops with an actionable message instead.

Installing the JDK afterwards is not enough on its own: the Gradle
daemon caches JVM metadata for its whole lifetime, so a daemon started
while only the JRE was present replays the same error. Both the new
check and the README now say to run ./gradlew --stop.

Also correct the JDK prerequisites: record that 8, 11, 17 and 21 are
supported, as the java-compatibility-test CI matrix already exercises,
note that 1.8 support will be removed in PXF 3.0, and fix the example
JAVA_HOME, which used a RHEL-style path that does not exist on
Debian/Ubuntu.

Fixes apache#150
Comment thread README.md Outdated
@tuhaihe
tuhaihe merged commit 5872786 into apache:main Sep 10, 2026
80 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

make error: Ubuntu 22.04/ubuntu 24.04

2 participants