{"record":{"id":"214eeea97f9d17c4","repo":"juanfont/headscale","slug":"starting-headscale-container-w-n-ndocker-build-s","errorCode":null,"errorMessage":"starting headscale container: %w\\n\\nDocker build succeeded on retry, but container creation failed. Last %d lines of build output:\\n%s","messagePattern":"starting headscale container: %w\\\\n\\\\nDocker build succeeded on retry, but container creation failed\\. Last (.+?) lines of build output:\\\\n(.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"integration/hsic/hsic.go","lineNumber":570,"sourceCode":"\t\t\tlines := strings.Split(buildOutput, \"\\n\")\n\n\t\t\tconst maxLines = 100\n\n\t\t\tstartLine := 0\n\t\t\tif len(lines) > maxLines {\n\t\t\t\tstartLine = len(lines) - maxLines\n\t\t\t}\n\n\t\t\trelevantOutput := strings.Join(lines[startLine:], \"\\n\")\n\n\t\t\tif buildErr != nil {\n\t\t\t\t// The diagnostic build also failed - this is the real error\n\t\t\t\treturn nil, fmt.Errorf(\"starting headscale container: %w\\n\\nDocker build failed. Last %d lines of output:\\n%s\", err, maxLines, relevantOutput)\n\t\t\t}\n\n\t\t\tif buildOutput != \"\" {\n\t\t\t\t// Build succeeded on retry but container creation still failed\n\t\t\t\treturn nil, fmt.Errorf(\"starting headscale container: %w\\n\\nDocker build succeeded on retry, but container creation failed. Last %d lines of build output:\\n%s\", err, maxLines, relevantOutput)\n\t\t\t}\n\n\t\t\t// No output at all - diagnostic build command may have failed\n\t\t\treturn nil, fmt.Errorf(\"starting headscale container: %w\\n\\nUnable to get diagnostic build output (command may have failed silently)\", err)\n\t\t}\n\t}\n\n\tlog.Printf(\"Created %s container\\n\", hsic.hostname)\n\n\thsic.container = container\n\n\t// Get the dynamically assigned host port for metrics/pprof\n\thsic.hostMetricsPort = container.GetHostPort(\"9090/tcp\")\n\n\tlog.Printf(\n\t\t\"Headscale %s metrics available at http://localhost:%s/metrics (debug at http://localhost:%s/debug/)\\n\",\n\t\thsic.hostname,\n\t\thsic.hostMetricsPort,","sourceCodeStart":552,"sourceCodeEnd":588,"githubUrl":"https://github.com/juanfont/headscale/blob/565fd254d06c4c7f9a8cad1714a43445c79ba420/integration/hsic/hsic.go#L552-L588","documentation":"Diagnostic variant when the initial container start failed but the diagnostic rebuild SUCCEEDED (buildOutput != \"\", buildErr == nil). This means the image builds cleanly, yet container creation from it failed — the wrapped err is a runtime problem (port allocation, network creation, capability flags, name collision), not a build problem.","triggerScenarios":"BuildAndRunWithBuildOptions fails at the run stage: DockerRestartPolicy/DockerAllowLocalIPv6/DockerAllowNetworkAdministration options rejected (e.g. IPv6 disabled on the host or no NET_ADMIN capability), duplicate container name, or host port exhaustion; the subsequent diagnostic build succeeds, proving the image is fine.","commonSituations":"Docker daemon without IPv6 support; rootless Docker or restricted environments denying network-administration capability; leftover containers with the same auto-generated name from a crashed run.","solutions":["Focus on the wrapped run error, not the build output — the image built successfully","Check the Docker network supports IPv6 (dockertestutil.DockerAllowLocalIPv6 requirement)","Remove stale containers/networks: `go run ./cmd/hi cleanup` or docker rm leftover containers","On rootless/restricted Docker, ensure NET_ADMIN capability is permitted"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// Check the host Docker network supports IPv6 before suites needing it\ndocker network inspect <net> --format '{{.EnableIPv6}}'","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Distinguish this variant: image builds fine, container run fails — investigate runtime options","Ensure IPv6 is enabled on the Docker network and NET_ADMIN is allowed","Clean stale same-name containers before runs"],"tags":["integration-test","docker","container-runtime","ipv6"],"backgroundTag":null,"analyzedSha":"565fd254d06c4c7f9a8cad1714a43445c79ba420","analyzedAt":"2026-08-15T13:12:30.133Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}