{"record":{"id":"6d1862985b2b861b","repo":"juanfont/headscale","slug":"creating-docker-client-w-6d1862","errorCode":null,"errorMessage":"creating Docker client: %w","messagePattern":"creating Docker client: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"cmd/hi/docker.go","lineNumber":41,"sourceCode":"\t\"github.com/juanfont/headscale/integration/dockertestutil\"\n)\n\nconst defaultDirPerm = 0o755\n\nvar (\n\tErrTestFailed              = errors.New(\"test failed\")\n\tErrUnexpectedContainerWait = errors.New(\"unexpected end of container wait\")\n\tErrNoDockerContext         = errors.New(\"no docker context found\")\n\tErrMemoryLimitViolations   = errors.New(\"container(s) exceeded memory limits\")\n)\n\n// runTestContainer executes integration tests in a Docker container.\n//\n//nolint:gocyclo // complex test orchestration function\nfunc runTestContainer(ctx context.Context, config *RunConfig) error {\n\tcli, err := createDockerClient(ctx)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"creating Docker client: %w\", err)\n\t}\n\tdefer cli.Close()\n\n\trunID := dockertestutil.GenerateRunID()\n\tcontainerName := \"headscale-test-suite-\" + runID\n\tlogsDir := filepath.Join(config.LogsDir, runID)\n\n\tif config.Verbose {\n\t\tlog.Printf(\"Run ID: %s\", runID)\n\t\tlog.Printf(\"Container name: %s\", containerName)\n\t\tlog.Printf(\"Logs directory: %s\", logsDir)\n\t}\n\n\tabsLogsDir, err := filepath.Abs(logsDir)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"getting absolute path for logs directory: %w\", err)\n\t}\n","sourceCodeStart":23,"sourceCodeEnd":59,"githubUrl":"https://github.com/juanfont/headscale/blob/565fd254d06c4c7f9a8cad1714a43445c79ba420/cmd/hi/docker.go#L23-L59","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Run `docker version` — fix whatever it reports first","Start the daemon (systemctl start docker / open Docker Desktop)","Fix environment: DOCKER_HOST, DOCKER_CONTEXT, `docker context use default`","Ensure group membership: sudo usermod -aG docker $USER, then re-login","Validate the whole setup with `go run ./cmd/hi doctor`"],"exampleFix":"# before\nsystemctl is-active docker   # inactive\ngo run ./cmd/hi run TestACL  # creating Docker client: ...\n\n# after\nsudo systemctl start docker\ngo run ./cmd/hi run TestACL","handlingStrategy":"validation","validationCode":"// Pre-flight before hi run: daemon must respond to Ping.\ncli, err := client.NewClientWithOpts(client.FromEnv, client.WithAPIVersionNegotiation())\nif err != nil { log.Fatalf(\"docker client: %v\", err) }\ndefer cli.Close()\nif _, err := cli.Ping(context.Background()); err != nil {\n\tlog.Fatalf(\"docker daemon unreachable: %v\", err)\n}","typeGuard":null,"tryCatchPattern":"Stop on client-creation failure and fix the environment (daemon, DOCKER_HOST, context, permissions); do not retry the test run until `docker version` succeeds.","preventionTips":["Make `docker version` (or `hi doctor`) the first step of every test workflow","Mount the docker socket correctly in CI containers","Automate daemon start (systemctl enable docker) on dev machines","Never assume a previous session's DOCKER_HOST is still valid"],"tags":["docker","client-init","integration-tests","hi"],"backgroundTag":null,"analyzedSha":"565fd254d06c4c7f9a8cad1714a43445c79ba420","analyzedAt":"2026-08-15T13:12:30.133Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}