spring-projects/spring-boot · critical · DockerConnectionException

Connection to the Docker daemon at '{}' failed with error "{

Error message

Connection to the Docker daemon at '{}' failed with error "{}"; ensure the Docker daemon is running and accessible

What it means

HttpClientTransport.execute caught IOException | URISyntaxException from client.executeOpen (or request.getUri()) and threw DockerConnectionException. The message is built by DockerConnectionException.buildMessage: 'Connection to the Docker daemon at <host> failed with error "<cause message>"; ensure the Docker daemon is running and accessible'. A JNA LastErrorException in the cause chain is unwrapped specially. This fires whenever the daemon cannot be reached at all, as opposed to a daemon that responds with an error (which is error 73).

Source

Thrown at buildpack/spring-boot-buildpack-platform/src/main/java/org/springframework/boot/buildpack/platform/docker/transport/HttpClientTransport.java:176

	}

	private Response execute(HttpUriRequest request) {
		try {
			beforeExecute(request);
			ClassicHttpResponse response = this.client.executeOpen(this.host, request, null);
			int statusCode = response.getCode();
			if (statusCode >= 400 && statusCode <= 500) {
				byte[] content = readContent(response);
				response.close();
				Errors errors = (statusCode != 500) ? deserializeErrors(content) : null;
				Message message = deserializeMessage(content);
				throw new DockerEngineException(this.host.toHostString(), request.getUri(), statusCode,
						response.getReasonPhrase(), errors, message, content);
			}
			return new HttpClientResponse(response);
		}
		catch (IOException | URISyntaxException ex) {
			throw new DockerConnectionException(this.host.toHostString(), ex);
		}
	}

	protected void beforeExecute(HttpRequest request) {
	}

	private byte @Nullable [] readContent(ClassicHttpResponse response) throws IOException {
		HttpEntity entity = response.getEntity();
		if (entity == null) {
			return null;
		}
		try (InputStream stream = entity.getContent()) {
			return (stream != null) ? stream.readAllBytes() : null;
		}
	}

	private @Nullable Errors deserializeErrors(byte @Nullable [] content) {
		if (content == null) {

View on GitHub (pinned to 270dfe353f)

Solutions

Confirm the daemon is reachable with the same DOCKER_HOST: `docker info` or `docker version`.
Start the daemon: Docker Desktop, or `sudo systemctl start docker` on Linux.
Fix socket access: `sudo usermod -aG docker $USER` then log out/in, or chmod the socket.
Correct the DOCKER_HOST value (scheme://host:port for tcp, unix:///path for sockets).

Defensive patterns

Strategy: validation

Validate before calling

// Health-check the daemon before invoking the build
Process p = new ProcessBuilder("docker", "info").redirectErrorStream(true).start();
if (p.waitFor() != 0) {
    throw new IllegalStateException(
        "Docker daemon is not reachable. Start Docker and verify DOCKER_HOST="
        + System.getenv().getOrDefault("DOCKER_HOST", "(default)"));
}

Try / catch

try {
    transport.get(uri);
} catch (DockerConnectionException ex) {
    // ex.getMessage() already names the host and underlying error;
    // surface a hint to start the daemon / fix DOCKER_HOST / socket permissions
    throw ex;
}

Prevention

Add a `docker info` healthcheck at the start of CI pipelines.
Validate the DOCKER_HOST format (unix:///path or tcp://host:port).
On Linux, ensure the build user is in the docker group or the socket is readable.

When it happens

Trigger: client.executeOpen(host, request, null) at line 163 throws IOException (connection refused, socket not found, timeout, TLS handshake failure, unknown host) or request.getUri() throws URISyntaxException because DOCKER_HOST is malformed.

Common situations: Local Docker Desktop not started; DOCKER_HOST=unix:///var/run/docker.sock but the socket is missing or owned by root with no group access; remote DOCKER_HOST behind a firewall or wrong port; DOCKER_HOST typo (e.g. tcp:/docker:2375 with a single slash); TLS cert mismatch against a tcp:// daemon.

Related errors

AI-assisted analysis of spring-projects/spring-boot@270dfe353f (2026-08-11). Data as JSON: /api/errors/696abade43da35f1. Report an issue: GitHub.