juanfont/headscale · error

ensuring image availability: %w

Error message

ensuring image availability: %w

What it means

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.

Source

Thrown at cmd/hi/docker.go:83

	if config.CleanBefore {
		if config.Verbose {
			log.Printf("Running pre-test cleanup...")
		}

		err := cleanupBeforeTest(ctx)
		if err != nil && config.Verbose {
			log.Printf("Warning: pre-test cleanup failed: %v", err)
		}
	}

	goTestCmd := buildGoTestCommand(config)
	if config.Verbose {
		log.Printf("Command: %s", strings.Join(goTestCmd, " "))
	}

	imageName := "golang:" + config.GoVersion
	if err := ensureImageAvailable(ctx, cli, imageName, config.Verbose); err != nil { //nolint:noinlineerr
		return fmt.Errorf("ensuring image availability: %w", err)
	}

	resp, err := createGoTestContainer(ctx, cli, config, containerName, absLogsDir, goTestCmd)
	if err != nil {
		return fmt.Errorf("creating container: %w", err)
	}

	if config.Verbose {
		log.Printf("Created container: %s", resp.ID)
	}

	if err := cli.ContainerStart(ctx, resp.ID, container.StartOptions{}); err != nil { //nolint:noinlineerr
		return fmt.Errorf("starting container: %w", err)
	}

	log.Printf("Starting test: %s", config.TestPattern)
	log.Printf("Run ID: %s", runID)
	log.Printf("Monitor with: docker logs -f %s", containerName)

View on GitHub (pinned to 565fd254d0)

Solutions

1. Verify Docker is reachable: `docker info` (and `docker context ls` if using colima/remote contexts).
2. Pre-pull the image manually: `docker pull golang:$(go version | cut -d' ' -f3 | tr -d go)` to see the real pull error.
3. Check the GoVersion configured in RunConfig is a valid published tag.
4. If rate-limited by Docker Hub, log in (`docker login`) or configure registry mirrors, then re-run.
5. Re-run with `--verbose` so `ensureImageAvailable` logs which stage (inspect/auth/pull) failed.

Example fix

// before: running with an unvalidated GoVersion
hi run TestACL --go-version 1.26.

// after: use a real tag and pre-pull
docker pull golang:1.26.1
hi run TestACL

// before invoking the runner, confirm image availability cheaply
img := "golang:" + cfg.GoVersion
if err := exec.Command("docker", "image", "inspect", img).Run(); err != nil {
    if err := exec.Command("docker", "pull", img).Run(); err != nil {
        return fmt.Errorf("pre-pull %s failed: %w", img, err)
    }
}

if err := runDockerTest(ctx, config); err != nil {
    if strings.Contains(err.Error(), "ensuring image availability") {
        // image/registry problem: check network, docker login, pre-pull, then retry once
    }
    return err
}

When it happens

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

Common situations: 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.

Related errors

• creating container: %w
• pulling image %s: %w
• reading pull output: %w
• extracting logs: %w
• pre-flight checks failed: %w

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