{"record":{"id":"c6f9267b7a907d97","repo":"juanfont/headscale","slug":"running-pre-built-headscale-container-q-w","errorCode":null,"errorMessage":"running pre-built headscale container %q: %w","messagePattern":"running pre-built headscale container %q: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"integration/hsic/hsic.go","lineNumber":533,"sourceCode":"\tif prebuiltImage != \"\" {\n\t\tlog.Printf(\"Using pre-built headscale image: %s\", prebuiltImage) //nolint:gosec // G706: integration-only log of trusted env value\n\t\t// Parse image into repository and tag\n\t\trepo, tag, ok := strings.Cut(prebuiltImage, \":\")\n\t\tif !ok {\n\t\t\treturn nil, errInvalidHeadscaleImageFormat\n\t\t}\n\n\t\trunOptions.Repository = repo\n\t\trunOptions.Tag = tag\n\n\t\tcontainer, err = pool.RunWithOptions(\n\t\t\trunOptions,\n\t\t\tdockertestutil.DockerRestartPolicy,\n\t\t\tdockertestutil.DockerAllowLocalIPv6,\n\t\t\tdockertestutil.DockerAllowNetworkAdministration,\n\t\t)\n\t\tif err != nil {\n\t\t\treturn nil, fmt.Errorf(\"running pre-built headscale container %q: %w\", prebuiltImage, err)\n\t\t}\n\t} else if util.IsCI() {\n\t\treturn nil, errHeadscaleImageRequiredInCI\n\t} else {\n\t\tcontainer, err = pool.BuildAndRunWithBuildOptions(\n\t\t\theadscaleBuildOptions,\n\t\t\trunOptions,\n\t\t\tdockertestutil.DockerRestartPolicy,\n\t\t\tdockertestutil.DockerAllowLocalIPv6,\n\t\t\tdockertestutil.DockerAllowNetworkAdministration,\n\t\t)\n\t\tif err != nil {\n\t\t\t// Try to get more detailed build output\n\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","sourceCodeStart":515,"sourceCodeEnd":551,"githubUrl":"https://github.com/juanfont/headscale/blob/565fd254d06c4c7f9a8cad1714a43445c79ba420/integration/hsic/hsic.go#L515-L551","documentation":"Returned when pool.RunWithOptions fails for a pre-built headscale image (set via the prebuilt-image option: repository/tag parsed from prebuiltImage). This path skips the local Docker build and runs an already-built image; failure means the image could not be pulled or the container could not be created.","triggerScenarios":"Passing WithPrebuiltImage / HEADSCALE_PREBUILT_IMAGE (required in CI when not building) and either the image does not exist in the registry, credentials are missing for a private registry, or Docker daemon rejects the run options (network/IPv6 capabilities).","commonSituations":"CI job referencing an image that was never pushed; typo'd repo:tag; unauthenticated pull from a private registry; local runner never loaded the image; note that in CI (util.IsCI()) the absence of a prebuilt image yields errHeadscaleImageRequiredInCI instead.","solutions":["Verify the image exists: docker pull <repo:tag> on the same host","Check the prebuiltImage string parses into the expected repository and tag (see repo/tag assignment just above)","Ensure registry credentials are configured (docker login) for private registries","Locally, omit the prebuilt option to fall back to BuildAndRunWithBuildOptions"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// Verify the prebuilt image exists locally before running\nif _, err := exec.Command(\"docker\", \"image\", \"inspect\", prebuiltImage).Output(); err != nil {\n    return nil, fmt.Errorf(\"prebuilt image %q not present; build or pull it first\", prebuiltImage)\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["docker pull <repo:tag> before the suite when using prebuilt images","Keep the image string as repo:tag with no stray whitespace","In CI, ensure the image-publish step completed before test jobs run"],"tags":["integration-test","docker","prebuilt-image","registry"],"backgroundTag":null,"analyzedSha":"565fd254d06c4c7f9a8cad1714a43445c79ba420","analyzedAt":"2026-08-15T13:12:30.133Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}