juanfont/headscale · error

listing images: %w

Error message

listing images: %w

What it means

Returned by cleanOldImages when cli.ImageList(All:true) fails while enumerating images to find test-related ones (hs-*, headscale-integration, tailscale). API-level failure causes: daemon unreachable mid-call, permission denial, API version mismatch, or proxies blocking the /images/json endpoint.

Source

Thrown at cmd/hi/cleanup.go:264

		fmt.Println("No unused networks found to remove")
	}

	return nil
}

// cleanOldImages removes test-related and old dangling Docker images.
func cleanOldImages(ctx context.Context) error {
	cli, err := createDockerClient(ctx)
	if err != nil {
		return fmt.Errorf("creating Docker client: %w", err)
	}
	defer cli.Close()

	images, err := cli.ImageList(ctx, image.ListOptions{
		All: true,
	})
	if err != nil {
		return fmt.Errorf("listing images: %w", err)
	}

	removed := 0

	for _, img := range images {
		shouldRemove := false

		for _, tag := range img.RepoTags {
			if strings.Contains(tag, "hs-") ||
				strings.Contains(tag, "headscale-integration") ||
				strings.Contains(tag, "tailscale") {
				shouldRemove = true
				break
			}
		}

		if len(img.RepoTags) == 0 && time.Unix(img.Created, 0).Before(time.Now().Add(-7*24*time.Hour)) {
			shouldRemove = true

View on GitHub (pinned to 565fd254d0)

Solutions

1. Reproduce manually: docker images -a
2. Enable the images endpoint on socket proxies (-e IMAGES=1)
3. Unset DOCKER_API_VERSION; upgrade very old engines
4. Retry after daemon connectivity is restored

Example fix

# docker-socket-proxy: allow image listing
-e IMAGES=1

docker images -a   # must succeed; repro of cli.ImageList

Reproduce with docker images; proxy whitelist issues appear there directly. Retry transient failures after daemon recovery.

When it happens

Trigger: Running `hi cleanup` when the daemon restarts; DOCKER_API_VERSION pinned to an unsupported value; docker-socket proxy without IMAGES enabled; remote daemon connection dropped.

Common situations: Socket proxies with narrow whitelists in CI; daemon upgrades mid-session; flaky remote contexts; disk-full daemons refusing some API calls.

Related errors

• cleaning stale test containers: %w
• pruning networks: %w
• listing containers: %w
• listing containers for run %s: %w
• listing stopped containers: %w

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