What causes "pruning networks: %w" in juanfont/headscale?

Check the wrapped message after 'pruning networks:' to identify the API-level cause

pruning networks: %w

Error message

pruning networks: %w

What it means

Returned by cleanupBeforeTest when pruneDockerNetworks fails. pruneDockerNetworks creates a Docker client and calls cli.NetworksPrune, which asks the daemon to delete unused networks. Failures come from daemon connectivity/permission problems or from the daemon rejecting the prune call itself (e.g. networks still referenced by containers on some setups).

Source

Thrown at cmd/hi/cleanup.go:29

	"github.com/cenkalti/backoff/v5"
	"github.com/docker/docker/api/types/container"
	"github.com/docker/docker/api/types/filters"
	"github.com/docker/docker/api/types/image"
	"github.com/docker/docker/client"
	"github.com/docker/docker/errdefs"
)

// cleanupBeforeTest performs cleanup operations before running tests.
// Only removes stale (stopped/exited) test containers to avoid interfering with concurrent test runs.
func cleanupBeforeTest(ctx context.Context) error {
	err := cleanupStaleTestContainers(ctx)
	if err != nil {
		return fmt.Errorf("cleaning stale test containers: %w", err)
	}

	if err := pruneDockerNetworks(ctx); err != nil { //nolint:noinlineerr
		return fmt.Errorf("pruning networks: %w", err)
	}

	return nil
}

// cleanupAfterTest removes the test container and all associated integration test containers for the run.
func cleanupAfterTest(ctx context.Context, cli *client.Client, containerID, runID string) error {
	// Remove the main test container
	err := cli.ContainerRemove(ctx, containerID, container.RemoveOptions{
		Force: true,
	})
	if err != nil {
		return fmt.Errorf("removing test container: %w", err)
	}

	// Clean up integration test containers for this run only
	if runID != "" {
		err := killTestContainersByRunID(ctx, runID)

View on GitHub (pinned to 565fd254d0)

Solutions

Check the wrapped message after 'pruning networks:' to identify the API-level cause
Verify `docker network prune` works manually with the same user and DOCKER_HOST
Stop containers that hold references to custom networks, or accept that prune is best-effort and fix the connectivity issue
Ensure DOCKER_HOST/DOCKER_CONTEXT point to the intended daemon

Defensive patterns

Strategy: retry

Try / catch

Treat prune failures as best-effort: log and continue if the underlying test goal matters more; retry once after verifying `docker network prune` succeeds manually.

Prevention

Periodically prune networks manually on shared CI machines so hi's prune has nothing conflicting to do
Verify daemon health before test runs
Avoid attaching unrelated containers to custom networks on machines running integration tests

When it happens

Trigger: Pre-test cleanup running when the Docker daemon is unreachable or the user cannot access it; NetworksPrune returning an API error such as a conflict because a custom network is in use by another container outside the test's control.

Common situations: Shared CI machines with other containers attached to custom networks; remote DOCKER_HOST where pruning is disallowed; transient daemon restarts mid-cleanup; user not in the docker group.

Related errors

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