{"record":{"id":"0c1a42cdc4969e92","repo":"juanfont/headscale","slug":"ensuring-image-availability-w","errorCode":null,"errorMessage":"ensuring image availability: %w","messagePattern":"ensuring image availability: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/hi/docker.go","lineNumber":83,"sourceCode":"\tif config.CleanBefore {\n\t\tif config.Verbose {\n\t\t\tlog.Printf(\"Running pre-test cleanup...\")\n\t\t}\n\n\t\terr := cleanupBeforeTest(ctx)\n\t\tif err != nil && config.Verbose {\n\t\t\tlog.Printf(\"Warning: pre-test cleanup failed: %v\", err)\n\t\t}\n\t}\n\n\tgoTestCmd := buildGoTestCommand(config)\n\tif config.Verbose {\n\t\tlog.Printf(\"Command: %s\", strings.Join(goTestCmd, \" \"))\n\t}\n\n\timageName := \"golang:\" + config.GoVersion\n\tif err := ensureImageAvailable(ctx, cli, imageName, config.Verbose); err != nil { //nolint:noinlineerr\n\t\treturn fmt.Errorf(\"ensuring image availability: %w\", err)\n\t}\n\n\tresp, err := createGoTestContainer(ctx, cli, config, containerName, absLogsDir, goTestCmd)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"creating container: %w\", err)\n\t}\n\n\tif config.Verbose {\n\t\tlog.Printf(\"Created container: %s\", resp.ID)\n\t}\n\n\tif err := cli.ContainerStart(ctx, resp.ID, container.StartOptions{}); err != nil { //nolint:noinlineerr\n\t\treturn fmt.Errorf(\"starting container: %w\", err)\n\t}\n\n\tlog.Printf(\"Starting test: %s\", config.TestPattern)\n\tlog.Printf(\"Run ID: %s\", runID)\n\tlog.Printf(\"Monitor with: docker logs -f %s\", containerName)","sourceCodeStart":65,"sourceCodeEnd":101,"githubUrl":"https://github.com/juanfont/headscale/blob/565fd254d06c4c7f9a8cad1714a43445c79ba420/cmd/hi/docker.go#L65-L101","documentation":"This error is returned by the `hi` integration-test runner when it cannot confirm that the `golang:<config.GoVersion>` Docker image is usable before creating the test container. It wraps failures from the whole availability pipeline: local image inspection, registry auth resolution, and the retried image pull. The image is required because the go test suite runs inside a `golang:` container.","triggerScenarios":"Calling `runDockerTest` (i.e. `hi run ...`) when the local Docker daemon is unreachable, the image inspect API returns an error other than NotFound, `docker context inspect` fails, registry auth cannot be built by `dockertestutil.RegistryAuth()`, or the image pull still fails after exponential backoff capped at 60 seconds (e.g. rate limits, offline network, invalid GoVersion tag like `golang:nonsense`).","commonSituations":"First run on a machine without the golang image and no network; Docker Hub rate limiting in CI; wrong `config.GoVersion`; Docker Desktop/colima daemon stopped; misconfigured DOCKER_HOST or docker context pointing at a dead remote daemon.","solutions":["Verify Docker is reachable: `docker info` (and `docker context ls` if using colima/remote contexts).","Pre-pull the image manually: `docker pull golang:$(go version | cut -d' ' -f3 | tr -d go)` to see the real pull error.","Check the GoVersion configured in RunConfig is a valid published tag.","If rate-limited by Docker Hub, log in (`docker login`) or configure registry mirrors, then re-run.","Re-run with `--verbose` so `ensureImageAvailable` logs which stage (inspect/auth/pull) failed."],"exampleFix":"// before: running with an unvalidated GoVersion\nhi run TestACL --go-version 1.26.\n\n// after: use a real tag and pre-pull\ndocker pull golang:1.26.1\nhi run TestACL","handlingStrategy":"validation","validationCode":"// before invoking the runner, confirm image availability cheaply\nimg := \"golang:\" + cfg.GoVersion\nif err := exec.Command(\"docker\", \"image\", \"inspect\", img).Run(); err != nil {\n    if err := exec.Command(\"docker\", \"pull\", img).Run(); err != nil {\n        return fmt.Errorf(\"pre-pull %s failed: %w\", img, err)\n    }\n}","typeGuard":null,"tryCatchPattern":"if err := runDockerTest(ctx, config); err != nil {\n    if strings.Contains(err.Error(), \"ensuring image availability\") {\n        // image/registry problem: check network, docker login, pre-pull, then retry once\n    }\n    return err\n}","preventionTips":["Pre-pull the golang image in CI before running hi.","Pin config.GoVersion to a tag that exists on Docker Hub.","Run `docker info` as a smoke check before starting test runs.","Authenticate to Docker Hub (`docker login`) to avoid anonymous rate limits."],"tags":["docker","image-pull","integration-tests","hi-runner","network"],"backgroundTag":null,"analyzedSha":"565fd254d06c4c7f9a8cad1714a43445c79ba420","analyzedAt":"2026-08-15T13:12:30.133Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}