juanfont/headscale · critical

creating Docker client: %w

Error message

creating Docker client: %w

What it means

Returned by runTestContainer when createDockerClient fails at the very start of an integration test run. This is the primary 'Docker is not usable' error for `hi run`: the client could not be built from DOCKER_HOST/context/default socket, so no test container can be started.

Source

Thrown at cmd/hi/docker.go:41

	"github.com/juanfont/headscale/integration/dockertestutil"
)

const defaultDirPerm = 0o755

var (
	ErrTestFailed              = errors.New("test failed")
	ErrUnexpectedContainerWait = errors.New("unexpected end of container wait")
	ErrNoDockerContext         = errors.New("no docker context found")
	ErrMemoryLimitViolations   = errors.New("container(s) exceeded memory limits")
)

// runTestContainer executes integration tests in a Docker container.
//
//nolint:gocyclo // complex test orchestration function
func runTestContainer(ctx context.Context, config *RunConfig) error {
	cli, err := createDockerClient(ctx)
	if err != nil {
		return fmt.Errorf("creating Docker client: %w", err)
	}
	defer cli.Close()

	runID := dockertestutil.GenerateRunID()
	containerName := "headscale-test-suite-" + runID
	logsDir := filepath.Join(config.LogsDir, runID)

	if config.Verbose {
		log.Printf("Run ID: %s", runID)
		log.Printf("Container name: %s", containerName)
		log.Printf("Logs directory: %s", logsDir)
	}

	absLogsDir, err := filepath.Abs(logsDir)
	if err != nil {
		return fmt.Errorf("getting absolute path for logs directory: %w", err)
	}

View on GitHub (pinned to 565fd254d0)

Solutions

1. Run `docker version` — fix whatever it reports first
2. Start the daemon (systemctl start docker / open Docker Desktop)
3. Fix environment: DOCKER_HOST, DOCKER_CONTEXT, `docker context use default`
4. Ensure group membership: sudo usermod -aG docker $USER, then re-login
5. Validate the whole setup with `go run ./cmd/hi doctor`

Example fix

# before
systemctl is-active docker   # inactive
go run ./cmd/hi run TestACL  # creating Docker client: ...

# after
sudo systemctl start docker
go run ./cmd/hi run TestACL

// Pre-flight before hi run: daemon must respond to Ping.
cli, err := client.NewClientWithOpts(client.FromEnv, client.WithAPIVersionNegotiation())
if err != nil { log.Fatalf("docker client: %v", err) }
defer cli.Close()
if _, err := cli.Ping(context.Background()); err != nil {
	log.Fatalf("docker daemon unreachable: %v", err)
}

Stop on client-creation failure and fix the environment (daemon, DOCKER_HOST, context, permissions); do not retry the test run until `docker version` succeeds.

When it happens

Trigger: Running `go run ./cmd/hi run <Test>` with the daemon stopped; DOCKER_HOST=... unreachable; docker context pointing at a deleted endpoint; permission denied on /var/run/docker.sock.

Common situations: Forgetting to start Docker Desktop; CI runners without the docker socket mounted; stale DOCKER_HOST from earlier shell sessions; users not in the docker group; rootless docker without env set.

Related errors

• cleaning stale test containers: %w
• creating Docker client: %w
• pruning networks: %w
• removing test container: %w
• cleaning up containers for run %s: %w

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