elastic/elasticsearch · error · GradleException

Configured JAVA_TOOLCHAIN_HOME {toolChainEnvVariable} does n

Error message

Configured JAVA_TOOLCHAIN_HOME {toolChainEnvVariable} does not point to a valid jdk installation.

What it means

Thrown by GlobalBuildInfoPlugin.resolveToolchainSpecFromEnv() when the JAVA_TOOLCHAIN_HOME environment variable is set but does not point to a valid JDK installation. The code constructs a File from the env var value, obtains JvmInstallationMetadata via the metadata detector, and checks isValidInstallation(). If invalid, it throws GradleException.

Source

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

            spec.getParameters().getBuildParams().set(buildParams);
        });

        // Enforce the minimum compiler version
        assertMinimumCompilerVersion(minimumCompilerVersion);

        // Print global build info header just before task execution
        // Only do this if we are the root build of a composite
        if (GradleUtils.isIncludedBuild(project) == false) {
            project.getGradle().getTaskGraph().whenReady(graph -> logGlobalBuildInfo(buildParams));
        }
    }

    private Provider<MetadataBasedToolChainMatcher> resolveToolchainSpecFromEnv() {
        return providers.environmentVariable("JAVA_TOOLCHAIN_HOME").map(toolChainEnvVariable -> {
            File toolChainDir = new File(toolChainEnvVariable);
            JvmInstallationMetadata metadata = metadataDetector.getMetadata(getJavaInstallation(toolChainDir));
            if (metadata.isValidInstallation() == false) {
                throw new GradleException(
                    "Configured JAVA_TOOLCHAIN_HOME " + toolChainEnvVariable + " does not point to a valid jdk installation."
                );
            }
            return new MetadataBasedToolChainMatcher(metadata);
        });
    }

    private String formatJavaVendorDetails(JvmInstallationMetadata runtimeJdkMetaData) {
        JvmVendor vendor = runtimeJdkMetaData.getVendor();
        return runtimeJdkMetaData.getVendor().getKnownVendor().name() + "/" + vendor.getRawVendor();
    }

    /* Introspect all versions of ES that may be tested against for backwards
     * compatibility. It is *super* important that this logic is the same as the
     * logic in VersionUtils.java. */
    private BwcVersions resolveBwcVersions(Version currentElasticsearchVersion) {
        String versionsFilePath = elvis(
            System.getProperty("BWC_VERSION_SOURCE"),

View on GitHub (pinned to db6a809a66)

Solutions

1. Verify the path is a full JDK: ls $JAVA_TOOLCHAIN_HOME/bin/java and ls $JAVA_TOOLCHAIN_HOME/release should both succeed.
2. Point JAVA_TOOLCHAIN_HOME to a valid JDK installation matching the required version (see minimumCompilerJava / minimumRuntimeJava in version.properties).
3. If the JDK was moved or removed, re-download or reinstall it and update the env var.
4. Unset JAVA_TOOLCHAIN_HOME if you want the Gradle toolchain auto-detection to resolve the JDK instead.

Example fix

# before
export JAVA_TOOLCHAIN_HOME=/opt/jre-17  # JRE, not JDK

# after
export JAVA_TOOLCHAIN_HOME=/opt/jdk-21  # full JDK with bin/java and release file

// Pre-build check: validate JAVA_TOOLCHAIN_HOME
String env = System.getenv("JAVA_TOOLCHAIN_HOME");
if (env != null) {
    File f = new File(env);
    if (!new File(f, "bin/java").exists() || !new File(f, "release").exists()) {
        throw new GradleException("JAVA_TOOLCHAIN_HOME is not a valid JDK: " + env);
    }
}

When it happens

Trigger: Environment variable JAVA_TOOLCHAIN_HOME is set to a path that is not a JDK root (e.g., a JRE, an empty directory, a JDK with missing release file, or a non-existent path). The metadata detector checks for standard JDK markers (release file, bin/java) and reports the installation as invalid.

Common situations: JAVA_TOOLCHAIN_HOME points to a JRE directory instead of a JDK. The path is stale (JDK was uninstalled or moved). The path points to a JDK download that was interrupted, leaving an incomplete installation. The env var was set for a different project with a different JDK location and was never updated.

Related errors

• The %s must be set to a JDK installation directory for Java
• Project requires Java version of {} or newer but Gradle JAVA
• Configuring a snapshot bwc distribution ('${distribution.get
• {message} you can address this by attending to the reported
• {className} can only be applied to the root project.

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