{"record":{"id":"259a5caa4dcb1f16","repo":"juanfont/headscale","slug":"resolving-registry-auth-w","errorCode":null,"errorMessage":"resolving registry auth: %w","messagePattern":"resolving registry auth: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/hi/docker.go","lineNumber":548,"sourceCode":"\tif err != nil {\n\t\treturn fmt.Errorf(\"checking local image availability: %w\", err)\n\t}\n\n\tif available {\n\t\tif verbose {\n\t\t\tlog.Printf(\"Image %s is available locally\", imageName)\n\t\t}\n\n\t\treturn nil\n\t}\n\n\tif verbose {\n\t\tlog.Printf(\"Image %s not found locally, pulling...\", imageName)\n\t}\n\n\tregistryAuth, err := dockertestutil.RegistryAuth()\n\tif err != nil {\n\t\treturn fmt.Errorf(\"resolving registry auth: %w\", err)\n\t}\n\n\t_, err = backoff.Retry(\n\t\tctx,\n\t\tfunc() (struct{}, error) {\n\t\t\treader, pullErr := cli.ImagePull(ctx, imageName, image.PullOptions{RegistryAuth: registryAuth})\n\t\t\tif pullErr != nil {\n\t\t\t\tif isPermanentDockerPullError(pullErr) {\n\t\t\t\t\treturn struct{}{}, backoff.Permanent(pullErr)\n\t\t\t\t}\n\n\t\t\t\treturn struct{}{}, fmt.Errorf(\"pulling image %s: %w\", imageName, pullErr)\n\t\t\t}\n\t\t\tdefer reader.Close()\n\n\t\t\tsink := io.Discard\n\t\t\tif verbose {\n\t\t\t\tsink = os.Stdout","sourceCodeStart":530,"sourceCodeEnd":566,"githubUrl":"https://github.com/juanfont/headscale/blob/565fd254d06c4c7f9a8cad1714a43445c79ba420/cmd/hi/docker.go#L530-L566","documentation":"Returned by `ensureImageAvailable` when `dockertestutil.RegistryAuth()` fails while preparing credentials for pulling the golang image. RegistryAuth builds the base64 registry auth blob (typically from docker config credentials); failure means credentials were unavailable or malformed — the pull is never attempted.","triggerScenarios":"No docker config file exists where expected while the helper requires one; DOCKER_CONFIG points to an unreadable/invalid path; a corrupted ~/.docker/config.json with malformed auth entries; helper fails to exec the docker CLI for credentials.","commonSituations":"Fresh CI machine with no `docker login` performed; rotated/deleted registry credentials; HOME unset in the CI job so ~/.docker resolves nowhere.","solutions":["Run `docker login` once as the same user to (re)create valid credentials.","Check `~/.docker/config.json` (or $DOCKER_CONFIG/config.json) is valid JSON.","Ensure HOME/DOCKER_CONFIG are set correctly in the environment invoking `hi`.","Read the wrapped message — it names what RegistryAuth could not obtain."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// ensure a docker config with credentials exists before pulling\nhome, _ := os.UserHomeDir()\ncfgPath := filepath.Join(home, \".docker\", \"config.json\")\nif _, err := os.Stat(cfgPath); err != nil {\n    return fmt.Errorf(\"no docker config at %s — run docker login: %w\", cfgPath, err)\n}","typeGuard":null,"tryCatchPattern":"if err := ensureImageAvailable(ctx, cli, image, verbose); err != nil {\n    if strings.Contains(err.Error(), \"resolving registry auth\") {\n        // credentials problem: docker login, fix ~/.docker/config.json, retry\n    }\n}","preventionTips":["Run `docker login` once on each CI machine/user that pulls images.","Keep ~/.docker/config.json valid JSON and readable.","Set HOME (or DOCKER_CONFIG) explicitly in CI environments."],"tags":["docker","registry-auth","credentials","configuration"],"backgroundTag":null,"analyzedSha":"565fd254d06c4c7f9a8cad1714a43445c79ba420","analyzedAt":"2026-08-15T13:12:30.133Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}