juanfont/headscale · error

checking local image availability: %w

Error message

checking local image availability: %w

What it means

Returned by `ensureImageAvailable` when its first step, `checkImageAvailableLocally`, itself errored (i.e. the 'inspecting image %s' wrapper bubbled up). It marks the availability-check stage so the later pull stage is never reached. Root causes are daemon-side, not 'image missing' — a missing image is a normal result that triggers a pull instead.

Source

Thrown at cmd/hi/docker.go:531

func checkImageAvailableLocally(ctx context.Context, cli *client.Client, imageName string) (bool, error) {
	_, _, err := cli.ImageInspectWithRaw(ctx, imageName) //nolint:staticcheck // SA1019: deprecated but functional
	if err != nil {
		if client.IsErrNotFound(err) { //nolint:staticcheck // SA1019: deprecated but functional
			return false, nil
		}

		return false, fmt.Errorf("inspecting image %s: %w", imageName, err)
	}

	return true, nil
}

// ensureImageAvailable pulls imageName if missing, using Docker Hub
// credentials and retrying transient errors.
func ensureImageAvailable(ctx context.Context, cli *client.Client, imageName string, verbose bool) error {
	available, err := checkImageAvailableLocally(ctx, cli, imageName)
	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)
	}

View on GitHub (pinned to 565fd254d0)

Solutions

1. Start/verify Docker: `docker info`.
2. Wait for dockerd readiness in CI before invoking `hi run`.
3. Check DOCKER_HOST / docker context points at a live daemon.
4. Re-login after changing docker group membership.

// readiness gate before running tests
if _, err := cli.Ping(ctx); err != nil {
    return fmt.Errorf("docker not ready: %w", err)
}

if err := runDockerTest(ctx, config); err != nil {
    if strings.Contains(err.Error(), "checking local image availability") {
        // daemon unreachable at startup: bring Docker up, then re-run
    }
}

When it happens

Trigger: Same underlying set as the inspect error: daemon down, socket permission denied, API errors on ImageInspectWithRaw, cancelled context before the run starts.

Common situations: Running `hi` without Docker running; group membership not refreshed after adding user to docker group; DOCKER_HOST pointing to a stale remote daemon; CI service container for dockerd not yet ready when `hi run` starts.

Related errors

• inspecting image %s: %w
• reaching DERP server: %w
• %s failed to fetch tailscale status: %w
• cleaning stale test containers: %w
• pruning networks: %w

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