elastic/elasticsearch · error · GradleException

{message} you can address this by attending to the reported

Error message

{message}
you can address this by attending to the reported issue, or removing the offending tasks from being executed.

What it means

A wrapper thrown by throwDockerRequiredException(String, Exception) whenever a Gradle task requires Docker but Docker is unavailable, too old, or malfunctioning. The method appends a generic remediation suffix to a context-specific message. It is called from three sites: no Docker binary found (line 194), Docker version below MINIMUM_DOCKER_VERSION (line 205), and Docker exited with a non-zero exit code (line 223).

Source

Thrown at build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/docker/DockerSupportService.java:363

    }

    /**
     * Searches the entries in {@link #DOCKER_COMPOSE_BINARIES} for the Docker Compose CLI. This method does
     * not check whether the installation appears usable, see {@link #getDockerAvailability()} instead.
     *
     * @return the path to a CLI, if available.
     */
    private Optional<String> getDockerComposePath() {
        // Check if the Docker binary exists
        return Stream.of(DOCKER_COMPOSE_BINARIES).filter(path -> new File(path).exists()).findFirst();
    }

    private void throwDockerRequiredException(final String message) {
        throwDockerRequiredException(message, null);
    }

    private void throwDockerRequiredException(final String message, Exception e) {
        throw new GradleException(
            message + "\nyou can address this by attending to the reported issue, or removing the offending tasks from being executed.",
            e
        );
    }

    public void storeInfo(Map<String, ServiceInfo> servicesInfos) {
        tcpPorts = servicesInfos.entrySet()
            .stream()
            .collect(Collectors.toMap(entry -> entry.getKey(), entry -> entry.getValue().getTcpPorts()));
        udpPorts = servicesInfos.entrySet()
            .stream()
            .collect(Collectors.toMap(entry -> entry.getKey(), entry -> entry.getValue().getUdpPorts()));
    }

    public Map<String, Map<Integer, Integer>> getTcpPorts() {
        return tcpPorts;
    }

View on GitHub (pinned to db6a809a66)

Solutions

1. Start the Docker daemon: systemctl start docker (Linux) or open Docker Desktop (macOS/Windows).
2. If Docker is installed but not found, set DOCKER_HOST or ensure /usr/bin/docker (or /usr/local/bin/docker) exists and is on PATH for the Gradle daemon process.
3. Upgrade Docker to at least MINIMUM_DOCKER_VERSION if the version is too old.
4. If you don't need Docker, exclude the offending tasks from the task graph (e.g., ./gradlew build -x dockerBuild --exclude-task ...).

// Pre-build Docker availability check
Process p = new ProcessBuilder("docker", "version").redirectErrorStream(true).start();
int exit = p.waitFor();
if (exit != 0) {
    throw new GradleException("Docker is not available. Start Docker daemon.");
}

// Wrap Docker-dependent task execution
tasks.matching { it.name.contains('docker') }.configureEach {
    doFirst {
        try {
            dockerSupport.get().assertDockerAvailableForTasks(List.of(it.getName()))
        } catch (GradleException e) {
            throw new StopExecutionException("Docker unavailable: skipping " + it.getName())
        }
    }
}

When it happens

Trigger: A task annotated or configured to require Docker (via DockerSupportService.assertDockerAvailableForTasks or similar) executes, and DockerSupportService.getDockerAvailability() reports: (1) availability.path == null (no binary in DOCKER_BINARIES or PATH), (2) isVersionHighEnough == false (Docker version < MINIMUM_DOCKER_VERSION), or (3) lastCommand failed with non-zero exit code.

Common situations: Docker daemon is not running on the developer's machine. Docker is installed but not on PATH in the Gradle worker's environment (common in IDE-launched builds). Docker is installed but the version is older than required for multi-stage builds. Docker daemon is running but is out of disk space or has socket permission issues, causing commands to fail.

Related errors

• {className} can only be applied to the root project.
• Failed to read /etc/os-release
• Failed to read {exclusionsFileAbsolutePath}
• Gradle {minimumGradleVersion}+ is required
• Configured JAVA_TOOLCHAIN_HOME {toolChainEnvVariable} does n

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