juanfont/headscale · error

creating Docker client: %w

Error message

creating Docker client: %w

What it means

Returned by killTestContainers when createDockerClient fails. createDockerClient negotiates a Docker client from the environment (DOCKER_HOST, DOCKER_CONTEXT, or the default unix socket), so this error means no usable daemon connection could be established: missing socket, unreachable remote host, or an invalid DOCKER_HOST URL.

Source

Thrown at cmd/hi/cleanup.go:60

		return fmt.Errorf("removing test container: %w", err)
	}

	// Clean up integration test containers for this run only
	if runID != "" {
		err := killTestContainersByRunID(ctx, runID)
		if err != nil {
			return fmt.Errorf("cleaning up containers for run %s: %w", runID, err)
		}
	}

	return nil
}

// killTestContainers terminates and removes all test containers.
func killTestContainers(ctx context.Context) error {
	cli, err := createDockerClient(ctx)
	if err != nil {
		return fmt.Errorf("creating Docker client: %w", err)
	}
	defer cli.Close()

	containers, err := cli.ContainerList(ctx, container.ListOptions{
		All: true,
	})
	if err != nil {
		return fmt.Errorf("listing containers: %w", err)
	}

	removed := 0

	for _, cont := range containers {
		if isTestContainerName(cont.Names) {
			if killAndRemove(ctx, cli, cont) {
				removed++
			}
		}

View on GitHub (pinned to 565fd254d0)

Solutions

1. Run `docker version` as the same user to confirm daemon connectivity
2. Start the daemon (systemctl start docker / open Docker Desktop)
3. Fix or unset DOCKER_HOST and DOCKER_CONTEXT; run `docker context ls` to pick a valid one
4. sudo usermod -aG docker $USER then log out/in for socket permission
5. For nonstandard sockets: export DOCKER_HOST=unix:///path/to/docker.sock

Example fix

# before
DOCKER_HOST=tcp://127.0.0.1:2375 go run ./cmd/hi kill
# error: creating Docker client: ...

# after (use local daemon)
unset DOCKER_HOST
go run ./cmd/hi kill

// Fail fast with a clear message if Docker is unusable.
func requireDocker(ctx context.Context) error {
	cli, err := client.NewClientWithOpts(client.FromEnv, client.WithAPIVersionNegotiation())
	if err != nil {
		return fmt.Errorf("docker client: %w", err)
	}
	defer cli.Close()
	if _, err := cli.Ping(ctx); err != nil {
		return fmt.Errorf("docker daemon unreachable: %w", err)
	}
	return nil
}

Distinguish client-creation errors (config/env problem — fix environment) from API errors (daemon problem — restart/retry) by inspecting the wrapped error.

When it happens

Trigger: Running `hi kill` (or any path into killTestContainers) with the Docker daemon stopped, DOCKER_HOST set to a dead URL (e.g. tcp://127.0.0.1:2375 with nothing listening), a nonexistent docker context, or without read permission on /var/run/docker.sock.

Common situations: Fresh machines where the user is not in the docker group; DOCKER_HOST exported for a remote daemon that is since gone; Docker Desktop not started; rootless daemon socket path not set; CI runners where the docker socket is mounted at a nonstandard path.

Related errors

• creating Docker client: %w
• cleaning stale test containers: %w
• listing containers: %w
• getting docker context: %w
• creating temp dir: %w

AI-assisted analysis of juanfont/headscale@565fd254d0 (2026-08-15). Data as JSON: /api/errors/042bc9b6e89ff855. Report an issue: GitHub.