juanfont/headscale · error

listing containers: %w

Error message

listing containers: %w

What it means

Returned by killTestContainers when cli.ContainerList(All:true) fails while enumerating every container to find test ones. The Docker API call can fail due to daemon connectivity loss, insufficient permissions, or an API-version mismatch between the client library and the daemon.

Source

Thrown at cmd/hi/cleanup.go:68

		}
	}

	return nil
}

// killTestContainers terminates and removes all test containers.
func killTestContainers(ctx context.Context) error {
	cli, err := createDockerClient(ctx)
	if err != nil {
		return fmt.Errorf("creating Docker client: %w", err)
	}
	defer cli.Close()

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

	removed := 0

	for _, cont := range containers {
		if isTestContainerName(cont.Names) {
			if killAndRemove(ctx, cli, cont) {
				removed++
			}
		}
	}

	if removed > 0 {
		fmt.Printf("Removed %d test containers\n", removed)
	} else {
		fmt.Println("No test containers found to remove")
	}

View on GitHub (pinned to 565fd254d0)

Solutions

1. Retry after confirming `docker ps -a` works
2. Unset DOCKER_API_VERSION if it was pinned for another tool
3. Upgrade Docker Engine if it is far older than the client library expects
4. Check the wrapped message for the exact API error

Retry ContainerList once on transient errors; abort with the wrapped message if `docker ps -a` also fails manually.

When it happens

Trigger: Running `hi kill` when the daemon restarts mid-call; the negotiated API version being newer than the daemon supports (very old engine); permission denied on the socket; remote daemon dropping the connection.

Common situations: Docker being upgraded while the command runs; pinned DOCKER_API_VERSION env var set to an unsupported value; flaky remote daemon over TLS; CI runners recycling the daemon.

Related errors

• cleaning stale test containers: %w
• creating Docker client: %w
• listing containers for run %s: %w
• listing stopped containers: %w
• listing images: %w

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