juanfont/headscale · error

resolving registry auth: %w

Error message

resolving registry auth: %w

What it means

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.

Source

Thrown at cmd/hi/docker.go:548

	if err != nil {
		return fmt.Errorf("checking local image availability: %w", err)
	}

	if available {
		if verbose {
			log.Printf("Image %s is available locally", imageName)
		}

		return nil
	}

	if verbose {
		log.Printf("Image %s not found locally, pulling...", imageName)
	}

	registryAuth, err := dockertestutil.RegistryAuth()
	if err != nil {
		return fmt.Errorf("resolving registry auth: %w", err)
	}

	_, err = backoff.Retry(
		ctx,
		func() (struct{}, error) {
			reader, pullErr := cli.ImagePull(ctx, imageName, image.PullOptions{RegistryAuth: registryAuth})
			if pullErr != nil {
				if isPermanentDockerPullError(pullErr) {
					return struct{}{}, backoff.Permanent(pullErr)
				}

				return struct{}{}, fmt.Errorf("pulling image %s: %w", imageName, pullErr)
			}
			defer reader.Close()

			sink := io.Discard
			if verbose {
				sink = os.Stdout

View on GitHub (pinned to 565fd254d0)

Solutions

1. Run `docker login` once as the same user to (re)create valid credentials.
2. Check `~/.docker/config.json` (or $DOCKER_CONFIG/config.json) is valid JSON.
3. Ensure HOME/DOCKER_CONFIG are set correctly in the environment invoking `hi`.
4. Read the wrapped message — it names what RegistryAuth could not obtain.

// ensure a docker config with credentials exists before pulling
home, _ := os.UserHomeDir()
cfgPath := filepath.Join(home, ".docker", "config.json")
if _, err := os.Stat(cfgPath); err != nil {
    return fmt.Errorf("no docker config at %s — run docker login: %w", cfgPath, err)
}

if err := ensureImageAvailable(ctx, cli, image, verbose); err != nil {
    if strings.Contains(err.Error(), "resolving registry auth") {
        // credentials problem: docker login, fix ~/.docker/config.json, retry
    }
}

When it happens

Trigger: 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.

Common situations: Fresh CI machine with no `docker login` performed; rotated/deleted registry credentials; HOME unset in the CI job so ~/.docker resolves nowhere.

Related errors

• creating Docker client: %w
• writing headscale config to container: %w
• must be a positive duration
• checkPeriod is only valid with action "check"
• invalid localpart format, must be localpart:*@<domain>

AI-assisted analysis of juanfont/headscale@565fd254d0 (2026-08-15). Data as JSON: /api/errors/259a5caa4dcb1f16. Report an issue: GitHub.