elastic/elasticsearch · error · IllegalArgumentException

failIfUnavailable cannot be 'false' on elasticsearch distrib

Error message

failIfUnavailable cannot be 'false' on elasticsearch distribution [${name}] of type [${type}]

What it means

failIfUnavailable=false is only meaningful for docker distributions (where it allows a build to proceed when docker is absent). For any non-docker type, finalizeValues treats turning it off as a configuration error and throws, because non-docker distributions have no availability check to skip.

Source

Thrown at build-tools/src/main/java/org/elasticsearch/gradle/ElasticsearchDistribution.java:245

    // internal, make this distribution's configuration unmodifiable
    void finalizeValues() {
        if (getType() == ElasticsearchDistributionTypes.INTEG_TEST_ZIP) {
            if (platform.getOrNull() != null) {
                throw new IllegalArgumentException(
                    "platform cannot be set on elasticsearch distribution [" + name + "] of type [integ_test_zip]"
                );
            }
            if (bundledJdk.getOrNull() != null) {
                throw new IllegalArgumentException(
                    "bundledJdk cannot be set on elasticsearch distribution [" + name + "] of type [integ_test_zip]"
                );
            }
            return;
        }

        if (isDocker() == false && failIfUnavailable.get() == false) {
            throw new IllegalArgumentException(
                "failIfUnavailable cannot be 'false' on elasticsearch distribution [" + name + "] of type [" + getType() + "]"
            );
        }

        if (getType() == ElasticsearchDistributionTypes.ARCHIVE) {
            // defaults for archive, set here instead of via convention so integ-test-zip can verify they are not set
            if (platform.isPresent() == false) {
                platform.set(CURRENT_PLATFORM);
            }
        } else { // rpm, deb or docker
            if (platform.isPresent()) {
                throw new IllegalArgumentException(
                    "platform cannot be set on elasticsearch distribution [" + name + "] of type [" + getType() + "]"
                );
            }
            if (isDocker()) {
                if (bundledJdk.isPresent()) {
                    throw new IllegalArgumentException(

View on GitHub (pinned to db6a809a66)

Solutions

1. Only set failIfUnavailable=false for DOCKER distributions.
2. Leave it at its default (true) for non-docker types.
3. Branch on isDocker() before applying the flag.

Example fix

// before
distribution.type = ElasticsearchDistributionTypes.ARCHIVE
distribution.failIfUnavailable = false
// after
distribution.type = ElasticsearchDistributionTypes.ARCHIVE
// leave failIfUnavailable at its default (true)

if (!distribution.isDocker() && !distribution.getFailIfUnavailable()) {
    throw new IllegalArgumentException("failIfUnavailable=false is only valid for docker distributions");
}

static boolean failIfUnavailableAllowedFalse(ElasticsearchDistribution d) {
    return d.isDocker();
}

When it happens

Trigger: Calling setFailIfUnavailable(false) on a distribution whose type is ARCHIVE, INTEG_TEST_ZIP, RPM, or DEB, then freezing it. The check is `isDocker() == false && failIfUnavailable.get() == false`.

Common situations: A shared helper sets failIfUnavailable=false on all distributions to be permissive, not realising it is docker-specific; a copy-paste from a docker-only block; a refactor changed the type away from docker.

Related errors

• Cannot set Elasticsearch Distribution type to ${type}. Type
• platform cannot be set on elasticsearch distribution [${name
• bundledJdk cannot be set on elasticsearch distribution [${na
• License category name must be exactly 5 characters, got ${ca
• distribution type [${typeName}] for elasticsearch distributi

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