fix: clearer error when Docker daemon API < 1.40 (#4696)

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

README.md

@@ -81,6 +81,8 @@ See the [Agent Mode](https://dozzle.dev/guide/agent) documentation for more deta
 
 Dozzle uses automatic API negotiation, which works with most Docker configurations. Dozzle also works with [Colima](https://github.com/abiosoft/colima) and [Podman](https://podman.io/).
 
+Dozzle requires Docker Engine 19.03 or newer (API version 1.40+). Older daemons are not supported by the underlying Docker SDK.
+
 ### Installation on Podman
 
 By default, Podman doesn't have a background process, but you can enable the remote socket for Dozzle to work.

docs/guide/faq.md

@@ -4,6 +4,12 @@ title: FAQ
 
 # Frequently Asked Questions
 
+## Dozzle fails to start with `client version 1.x is too new`. What does this mean?
+
+Dozzle requires Docker Engine 19.03 or newer (API version 1.40+). Older daemons — for example Docker 18.06 (API 1.38) — are not supported by the underlying Docker SDK and will fail at startup with an error like `failed to create docker client: ... client version 1.54 is too new. Maximum supported API version is 1.38`.
+
+Upgrade Docker Engine to a supported version. As a temporary workaround, pin Dozzle to `v10.5.2` or earlier, which used a Docker SDK that still negotiated down to older API versions.
+
 ## How do I upgrade Dozzle?
 
 Dozzle follows standard Docker image practices. To upgrade, pull the new image and recreate the container:

docs/guide/getting-started.md

@@ -6,6 +6,9 @@ title: Getting Started
 
 Dozzle supports multiple ways to run the application. You can run it using Docker CLI, Docker Compose, Swarm, or Kubernetes. The following sections will guide you through the process of setting up Dozzle.
 
+> [!IMPORTANT]
+> Dozzle requires Docker Engine **19.03 or newer** (API version 1.40+). Older daemons are not supported by the underlying Docker SDK.
+
 > [!TIP]
 > If Docker Hub is blocked in your network, you can use the [GitHub Container Registry](https://ghcr.io/amir20/dozzle:latest) to pull the image. Use `ghcr.io/amir20/dozzle:latest` instead of `amir20/dozzle:latest`.
 

internal/docker/client.go

@@ -83,6 +83,10 @@ func NewLocalClient(hostname string) (*DockerClient, error) {
 		return nil, err
 	}
 
+	if _, err := cli.Ping(context.Background(), client.PingOptions{NegotiateAPIVersion: true}); err != nil {
+		return nil, fmt.Errorf("docker daemon unreachable or unsupported (minimum API version %s required): %w", client.MinAPIVersion, err)
+	}
+
 	infoResult, err := cli.Info(context.Background(), client.InfoOptions{})
 	if err != nil {
 		return nil, err
@@ -126,6 +130,10 @@ func NewRemoteClient(host container.Host) (*DockerClient, error) {
 		return nil, err
 	}
 
+	if _, err := cli.Ping(context.Background(), client.PingOptions{NegotiateAPIVersion: true}); err != nil {
+		return nil, fmt.Errorf("docker daemon unreachable or unsupported (minimum API version %s required): %w", client.MinAPIVersion, err)
+	}
+
 	host.Type = "remote"
 
 	return NewClient(cli, host), nil