docker daemon unreachable or unsupported

Error message

docker daemon unreachable or unsupported (minimum API version %s required): %w

What it means

NewLocalClient pings the Docker daemon with API version negotiation right after client creation; if the ping fails, the daemon is unreachable or older than the minimum supported API version, and the error wraps the underlying cause. This fails fast at startup instead of producing confusing per-call errors later.

Solutions

Mount the Docker socket when running in Docker: -v /var/run/docker.sock:/var/run/docker.sock
Verify DOCKER_HOST / endpoint is correct and the daemon is running (docker info on that host)
Check socket permissions (add the user to the docker group or run with appropriate access)
Upgrade the Docker Engine to a version supporting client.MinAPIVersion if the daemon is too old

Example fix

// before
docker run amir20/dozzle  # no docker.sock
// after
docker run -v /var/run/docker.sock:/var/run/docker.sock amir20/dozzle

Defensive patterns

Strategy: fallback

Validate before calling

sock := os.Getenv("DOCKER_HOST")
if sock == "" { sock = "unix:///var/run/docker.sock" }
// stat the socket / TCP dial before starting Dozzle

Try / catch

cli, err := NewLocalClient()
if err != nil && strings.Contains(err.Error(), "docker daemon unreachable") {
  // log hint about docker.sock mount / DOCKER_HOST and exit or retry with backoff
}

Prevention

Mount /var/run/docker.sock when running Dozzle in Docker
Verify DOCKER_HOST endpoints before launch
Keep Docker Engine upgraded to meet the client's MinAPIVersion
Check daemon status (systemctl status docker) and socket permissions on deploy

When it happens

Trigger: NewLocalClient is called (from Run, main, or CreateMultiHostService) and cli.Ping with NegotiateAPIVersion fails: no Docker socket at /var/run/docker.sock, daemon down, TCP endpoint wrong, or daemon older than client.MinAPIVersion.

Common situations: Dozzle container launched without mounting /var/run/docker.sock; DOCKER_HOST pointing to a dead TCP endpoint; remote daemon offline; very old Docker engine (< minimum API version) after a Dozzle upgrade; permissions on the socket.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

AI-assisted analysis of amir20/dozzle@d9463cbe21 (2026-09-07). Data as JSON: /api/errors/3d30fc985c222db9. Report an issue: GitHub.

Appendix: source

Thrown at internal/docker/client.go:95

	}

	return &DockerClient{
		cli:  cli,
		host: host,
		info: info,
	}
}

// NewLocalClient creates a new instance of Client with docker filters
func NewLocalClient(hostname string) (*DockerClient, error) {
	cli, err := client.New(client.FromEnv, client.WithUserAgent("Docker-Client/Dozzle"))

	if err != nil {
		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
	}
	info := infoResult.Info

	host := container.Host{
		Name:     info.Name,
		Endpoint: "local",
		Type:     "local",
	}

	if hostname != "" {
		host.Name = hostname
	}

View on GitHub (pinned to d9463cbe21)