{"record":{"id":"a877a3152536d920","repo":"elastic/elasticsearch","slug":"configured-java-toolchain-home-toolchainenvvariab","errorCode":null,"errorMessage":"Configured JAVA_TOOLCHAIN_HOME {toolChainEnvVariable} does not point to a valid jdk installation.","messagePattern":"Configured JAVA_TOOLCHAIN_HOME (.+?) does not point to a valid jdk installation\\.","errorType":"exception","errorClass":"GradleException","httpStatus":null,"severity":"error","filePath":"build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/info/GlobalBuildInfoPlugin.java","lineNumber":178,"sourceCode":"            spec.getParameters().getBuildParams().set(buildParams);\n        });\n\n        // Enforce the minimum compiler version\n        assertMinimumCompilerVersion(minimumCompilerVersion);\n\n        // Print global build info header just before task execution\n        // Only do this if we are the root build of a composite\n        if (GradleUtils.isIncludedBuild(project) == false) {\n            project.getGradle().getTaskGraph().whenReady(graph -> logGlobalBuildInfo(buildParams));\n        }\n    }\n\n    private Provider<MetadataBasedToolChainMatcher> resolveToolchainSpecFromEnv() {\n        return providers.environmentVariable(\"JAVA_TOOLCHAIN_HOME\").map(toolChainEnvVariable -> {\n            File toolChainDir = new File(toolChainEnvVariable);\n            JvmInstallationMetadata metadata = metadataDetector.getMetadata(getJavaInstallation(toolChainDir));\n            if (metadata.isValidInstallation() == false) {\n                throw new GradleException(\n                    \"Configured JAVA_TOOLCHAIN_HOME \" + toolChainEnvVariable + \" does not point to a valid jdk installation.\"\n                );\n            }\n            return new MetadataBasedToolChainMatcher(metadata);\n        });\n    }\n\n    private String formatJavaVendorDetails(JvmInstallationMetadata runtimeJdkMetaData) {\n        JvmVendor vendor = runtimeJdkMetaData.getVendor();\n        return runtimeJdkMetaData.getVendor().getKnownVendor().name() + \"/\" + vendor.getRawVendor();\n    }\n\n    /* Introspect all versions of ES that may be tested against for backwards\n     * compatibility. It is *super* important that this logic is the same as the\n     * logic in VersionUtils.java. */\n    private BwcVersions resolveBwcVersions(Version currentElasticsearchVersion) {\n        String versionsFilePath = elvis(\n            System.getProperty(\"BWC_VERSION_SOURCE\"),","sourceCodeStart":160,"sourceCodeEnd":196,"githubUrl":"https://github.com/elastic/elasticsearch/blob/db6a809a667c081ca1dc7500389d26975573215f/build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/info/GlobalBuildInfoPlugin.java#L160-L196","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify the path is a full JDK: ls $JAVA_TOOLCHAIN_HOME/bin/java and ls $JAVA_TOOLCHAIN_HOME/release should both succeed.","Point JAVA_TOOLCHAIN_HOME to a valid JDK installation matching the required version (see minimumCompilerJava / minimumRuntimeJava in version.properties).","If the JDK was moved or removed, re-download or reinstall it and update the env var.","Unset JAVA_TOOLCHAIN_HOME if you want the Gradle toolchain auto-detection to resolve the JDK instead."],"exampleFix":"# before\nexport JAVA_TOOLCHAIN_HOME=/opt/jre-17  # JRE, not JDK\n\n# after\nexport JAVA_TOOLCHAIN_HOME=/opt/jdk-21  # full JDK with bin/java and release file","handlingStrategy":"validation","validationCode":"// Pre-build check: validate JAVA_TOOLCHAIN_HOME\nString env = System.getenv(\"JAVA_TOOLCHAIN_HOME\");\nif (env != null) {\n    File f = new File(env);\n    if (!new File(f, \"bin/java\").exists() || !new File(f, \"release\").exists()) {\n        throw new GradleException(\"JAVA_TOOLCHAIN_HOME is not a valid JDK: \" + env);\n    }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Validate JAVA_TOOLCHAIN_HOME points to a full JDK (has bin/java and release file).","Unset JAVA_TOOLCHAIN_HOME if you want Gradle's auto-detection to find the JDK.","After installing or moving a JDK, update the env var."],"tags":["java-toolchain","environment","jdk","configuration","build-infrastructure"],"analyzedSha":"db6a809a667c081ca1dc7500389d26975573215f","analyzedAt":"2026-08-12T01:39:14.192Z","schemaVersion":2},"datasetVersion":"2026-08-12T06:17:24.410Z"}