{"record":{"id":"b0edb4e3542f1503","repo":"juanfont/headscale","slug":"starting-headscale-container-w-n-ndocker-build-f","errorCode":null,"errorMessage":"starting headscale container: %w\\n\\nDocker build failed. Last %d lines of output:\\n%s","messagePattern":"starting headscale container: %w\\\\n\\\\nDocker build failed\\. Last (.+?) lines of output:\\\\n(.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"integration/hsic/hsic.go","lineNumber":565,"sourceCode":"\t\t\tlog.Printf(\"Docker build/run failed, attempting to get detailed output...\")\n\n\t\t\tbuildOutput, buildErr := dockertestutil.RunDockerBuildForDiagnostics(dockerContextPath, IntegrationTestDockerFileName)\n\n\t\t\t// Show the last 100 lines of build output to avoid overwhelming the logs\n\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\")","sourceCodeStart":547,"sourceCodeEnd":583,"githubUrl":"https://github.com/juanfont/headscale/blob/565fd254d06c4c7f9a8cad1714a43445c79ba420/integration/hsic/hsic.go#L547-L583","documentation":"Diagnostic error emitted when the initial BuildAndRunWithBuildOptions failed AND a retry build (run purely to capture output) also failed (buildErr != nil). It wraps the original container-start error together with the last 100 lines of the diagnostic build output, so the message contains the actual Go/overlay build failure that prevented the image from being created.","triggerScenarios":"Local (non-CI) HeadscaleInContainer construction without a prebuilt image: the embedded Dockerfile build fails twice — e.g. Go compile error in the current working tree, broken Dockerfile, unreachable base image, or disk exhaustion during build.","commonSituations":"Running integration tests with a compile-broken working tree (the image builds the current headscale source); base image pull failing; corrupted Docker build cache; insufficient disk space.","solutions":["Read the appended build output lines — they contain the real compile/build error","Run `make build` locally first; fix any Go compile errors before integration tests","Clear Docker build cache (docker builder prune) if the failure is stale-cache related","Free disk space if the build fails during layer writes"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// Compile locally before integration tests\ngo build ./... || exit 1","typeGuard":null,"tryCatchPattern":"if err := hsic.NewHeadscaleInContainer(...); err != nil && strings.Contains(err.Error(), \"Docker build failed\") {\n    // the appended last-100-lines contain the real compile error; surface them verbatim\n    t.Fatalf(\"image build broken: %v\", err)\n}","preventionTips":["Run `make build` before integration tests so compile errors surface cheaply","Read the appended build output — it pinpoints the failing source line","Prune Docker build cache when failures look stale"],"tags":["integration-test","docker-build","diagnostics"],"backgroundTag":null,"analyzedSha":"565fd254d06c4c7f9a8cad1714a43445c79ba420","analyzedAt":"2026-08-15T13:12:30.133Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}