juanfont/headscale · warning

listing containers: %w

Error message

listing containers: %w

What it means

Returned by `waitForContainerFinalization` when `cli.ContainerList(All: true)` fails while it polls for all run-related containers to reach a final state (10s budget, 500ms tick). This is a Docker API listing failure, not a per-container problem — the purpose of the function is to ensure test containers flushed output before artifact extraction.

Source

Thrown at cmd/hi/docker.go:355

	statusCh, errCh := cli.ContainerWait(ctx, containerID, container.WaitConditionNotRunning)
	select {
	case err := <-errCh:
		if err != nil {
			return -1, fmt.Errorf("waiting for container: %w", err)
		}
	case status := <-statusCh:
		return int(status.StatusCode), nil
	}

	return -1, ErrUnexpectedContainerWait
}

// waitForContainerFinalization ensures all test containers have properly finished and flushed their output.
func waitForContainerFinalization(ctx context.Context, cli *client.Client, testContainerID string, verbose bool) error {
	// First, get all related test containers
	containers, err := cli.ContainerList(ctx, container.ListOptions{All: true})
	if err != nil {
		return fmt.Errorf("listing containers: %w", err)
	}

	testContainers := getCurrentTestContainers(containers, testContainerID, verbose)

	// Wait for all test containers to reach a final state
	maxWaitTime := 10 * time.Second
	checkInterval := 500 * time.Millisecond
	timeout := time.After(maxWaitTime)

	ticker := time.NewTicker(checkInterval)
	defer ticker.Stop()

	for {
		select {
		case <-timeout:
			if verbose {
				log.Printf("Timeout waiting for container finalization, proceeding with artifact extraction")
			}

View on GitHub (pinned to 565fd254d0)

Solutions

1. Confirm daemon health: `docker ps -a` works after the run.
2. Re-run the test once the daemon is stable.
3. If it recurs at test-end on loaded machines, check dockerd memory/OOM events in the journal.

// cheap daemon liveness check before starting the run
if _, err := cli.ContainerList(ctx, container.ListOptions{Limit: 1}); err != nil {
    return fmt.Errorf("docker list API unavailable: %w", err)
}

if err := runDockerTest(ctx, config); err != nil {
    if strings.Contains(err.Error(), "listing containers") && !errors.Is(err, ErrTestFailed) {
        // post-test finalization failed: test verdict stands; retry only if artifacts needed
    }
}

When it happens

Trigger: Daemon unreachable or erroring on the list endpoint right after the test container exits; context cancelled before finalization; API version negotiation issues against an old daemon.

Common situations: Daemon restarting exactly when the test finishes (heavy CI load); network blip to a remote Docker context; abrupt dockerd OOM-kill during large test runs.

Related errors

• listing containers: %w
• listing containers for run %s: %w
• listing stopped containers: %w
• listing images: %w
• ensuring image availability: %w

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