docker/compose · error

failed to list networks: %w

Error message

failed to list networks: %w

What it means

During 'docker compose down', the preliminary NetworkList call (filtered by project label and network name) failed at the API level. It is a wrapper — the underlying client/transport error (connection refused, timeout, permissions) tells the real story; no networks are removed when this fires.

Source

Thrown at pkg/compose/down.go:195

		if n.External {
			continue
		}
		// loop capture variable for op closure
		networkKey := key
		idOrName := n.Name
		ops = append(ops, func() error {
			return s.removeNetwork(ctx, networkKey, project.Name, idOrName)
		})
	}
	return ops
}

func (s *composeService) removeNetwork(ctx context.Context, composeNetworkName string, projectName string, name string) error {
	res, err := s.apiClient().NetworkList(ctx, client.NetworkListOptions{
		Filters: projectFilter(projectName).Add("label", networkFilter(composeNetworkName)),
	})
	if err != nil {
		return fmt.Errorf("failed to list networks: %w", err)
	}
	networks := res.Items

	if len(networks) == 0 {
		return nil
	}

	eventName := fmt.Sprintf("Network %s", name)
	s.events.On(removingEvent(eventName))

	var found int
	for _, net := range networks {
		if net.Name != name {
			continue
		}
		nwInspect, err := s.apiClient().NetworkInspect(ctx, net.ID, client.NetworkInspectOptions{})
		if errdefs.IsNotFound(err) {
			s.events.On(newEvent(eventName, api.Warning, "No resource found to remove"))

View on GitHub (pinned to ddc4b044b6)

Solutions

1. Check daemon health: docker info; restart if needed
2. Verify DOCKER_HOST/context still reachable
3. Retry docker compose down once connectivity is back (down is idempotent)
4. Increase client timeouts for slow remote engines

// connectivity pre-check before teardown
if _, err := cli.Info(ctx); err != nil {
    return fmt.Errorf("daemon unreachable, aborting down: %w", err)
}

// down is idempotent: retry on transient transport failures
for i := 0; i < 3; i++ {
    err := compose.Down(ctx, api.DownOptions{Project: p})
    if err == nil || !errdefs.IsUnavailable(err) && !errdefs.IsSystem(err) { break }
    time.Sleep(time.Duration(i+1) * time.Second)
}

When it happens

Trigger: removeNetwork -> apiClient().NetworkList erroring: daemon stopped mid-down, DOCKER_HOST unreachable, TLS/auth failure to remote engine, or request timeout during teardown ops.

Common situations: Running 'down' after the daemon crashed or was restarted; VPN/SSH tunnel for remote docker dropped; slow daemon under load timing out.

Related errors

• failed to create network %s: %w
• failed to remove network %s: %w
• unsupported protocol for address: %s
• unsupported network: %s
• named pipes are only available on Windows

AI-assisted analysis of docker/compose@ddc4b044b6 (2026-08-15). Data as JSON: /api/errors/1642acf67aaa5d82. Report an issue: GitHub.