elastic/elasticsearch · error · GradleException

The %s must be set to a JDK installation directory for Java

Error message

The %s must be set to a JDK installation directory for Java %d but is [%s] corresponding to [%s]

What it means

Thrown by GlobalBuildInfoPlugin.throwInvalidJavaHomeException() when a configured Java home directory does not point to a JDK of the required version. The message is formatted with String.format: description (e.g., 'runtime java.home'), expectedVersion, javaHome path, and actualVersion. Called from determineJavaVersion() when actualVersion.isCompatibleWith(requiredVersion) returns false.

Source

Thrown at build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/info/GlobalBuildInfoPlugin.java:369

            Stream.of(InstallationLocation.userDefined(Jvm.current().getJavaHome(), "Current JVM"))
        );
    }

    private Provider<String> getTestSeed() {
        return project.getProviders().of(TestSeedValueSource.class, spec -> {});
    }

    private static void throwInvalidJavaHomeException(String description, File javaHome, int expectedVersion, int actualVersion) {
        String message = String.format(
            Locale.ROOT,
            "The %s must be set to a JDK installation directory for Java %d but is [%s] corresponding to [%s]",
            description,
            expectedVersion,
            javaHome,
            actualVersion
        );

        throw new GradleException(message);
    }

    private static void assertMinimumCompilerVersion(JavaVersion minimumCompilerVersion) {
        JavaVersion currentVersion = Jvm.current().getJavaVersion();
        if (System.getProperty("idea.active", "false").equals("true") == false && minimumCompilerVersion.compareTo(currentVersion) > 0) {
            throw new GradleException(
                "Project requires Java version of " + minimumCompilerVersion + " or newer but Gradle JAVA_HOME is " + currentVersion
            );
        }
    }

    private RuntimeJava findRuntimeJavaHome() {
        Properties versionProperties = (Properties) project.getExtensions().getByName(VERSIONS_EXT);
        String bundledJdkVersion = versionProperties.getProperty("bundled_jdk");
        String bundledJdkMajorVersion = bundledJdkVersion.split("[.+]")[0];

        String runtimeJavaProperty = System.getProperty("runtime.java");
        if (runtimeJavaProperty != null) {

View on GitHub (pinned to db6a809a66)

Solutions

Check the required version: ./gradlew -q dependencies or inspect version.properties for minimumRuntimeJava.
Install the required JDK version and point runtime.java or RUNTIME_JAVA_HOME to it.
If using JAVA_TOOLCHAIN_HOME, ensure the toolchain JDK matches the required major version.
Verify the detected version: run java -version in the configured JAVA_HOME to confirm.

Example fix

# before
export RUNTIME_JAVA_HOME=/opt/jdk-17  # too old, project needs 21

# after
export RUNTIME_JAVA_HOME=/opt/jdk-21

Defensive patterns

Strategy: validation

Validate before calling

// Validate JDK version before build
int required = Integer.parseInt(getResourceContents("/minimumRuntimeVersion"));
JavaVersion actual = Jvm.current().getJavaVersion();
if (actual.getMajorVersion().toInt() < required) {
    throw new GradleException("JDK " + required + "+ required, found " + actual);
}

Prevention

Install the required JDK version and update JAVA_HOME / RUNTIME_JAVA_HOME.
Check version.properties for minimumRuntimeJava before building.
Use SDKMAN or jenv to manage multiple JDK versions and switch easily.

When it happens

Trigger: determineJavaVersion() is called with a javaHome File and a requiredVersion. The metadata detector reads the JDK version from javaHome. If the detected major version is not compatible with requiredVersion (typically the minimumRuntimeVersion from classpath resource or the bundled JDK major version), the exception is thrown.

Common situations: System property 'runtime.java' points to a JDK that is too old (e.g., Java 17 when Java 21 is required). RUNTIME_JAVA_HOME env var points to an older JDK. JAVA_TOOLCHAIN_HOME resolves to a toolchain with the wrong version. The required version was bumped in version.properties but the local JDK was not updated.

Related errors

AI-assisted analysis of elastic/elasticsearch@db6a809a66 (2026-08-12). Data as JSON: /api/errors/a3298d5a7f310843. Report an issue: GitHub.