juanfont/headscale · warning

listing containers for run %s: %w

Error message

listing containers for run %s: %w

What it means

Returned by killTestContainersByRunID when the label-filtered ContainerList (label hi.run-id=<runID>) fails. This is a Docker API-level failure: connectivity loss, permission denial, or (on ancient engines) poor handling of label filters. Distinct from removal failures — the run's containers were not even enumerated.

Source

Thrown at cmd/hi/cleanup.go:108

// killTestContainersByRunID terminates and removes all test containers for a specific run ID.
// This function filters containers by the hi.run-id label to only affect containers
// belonging to the specified test run, leaving other concurrent test runs untouched.
func killTestContainersByRunID(ctx context.Context, runID string) error {
	cli, err := createDockerClient(ctx)
	if err != nil {
		return fmt.Errorf("creating Docker client: %w", err)
	}
	defer cli.Close()

	// Filter containers by hi.run-id label
	containers, err := cli.ContainerList(ctx, container.ListOptions{
		All: true,
		Filters: filters.NewArgs(
			filters.Arg("label", "hi.run-id="+runID),
		),
	})
	if err != nil {
		return fmt.Errorf("listing containers for run %s: %w", runID, err)
	}

	removed := 0

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

	if removed > 0 {
		fmt.Printf("Removed %d containers for run ID %s\n", removed, runID)
	}

	return nil
}

// cleanupStaleTestContainers removes stopped/exited test containers without affecting running tests.

View on GitHub (pinned to 565fd254d0)

Solutions

1. Run the equivalent query manually: docker ps -a --filter label=hi.run-id=<runID>
2. Retry the operation once the daemon is stable
3. Unset DOCKER_API_VERSION if pinned; upgrade ancient Docker engines
4. Free disk/inodes if the daemon is crash-looping (check journalctl -u docker)

# Equivalent check for the exact filter hi uses
docker ps -a --filter "label=hi.run-id=<runID>"

Reproduce the list manually with the label filter; if that works, retry the hi command; if not, fix daemon/proxy configuration.

When it happens

Trigger: Daemon restarting at teardown; API version mismatch rejecting the filter; permission denied; network interruption to a remote daemon while listing.

Common situations: Concurrent CI jobs stressing the daemon; DOCKER_API_VERSION pinned incorrectly; remote docker contexts over unstable links; daemon crash-looping due to disk pressure.

Related errors

• cleaning up containers for run %s: %w
• cleaning stale test containers: %w
• pruning networks: %w
• removing test container: %w
• listing containers: %w

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