docker/compose · error

failed to remove network %s: %w

Error message

failed to remove network %s: %w

What it means

NetworkRemove returned a non-NotFound error while pruning a compose network during down. Still-in-use networks are only warned about and skipped; this error means the actual delete API call failed (permissions, daemon state, plugin driver error) and down aborts.

Source

Thrown at pkg/compose/down.go:231

			s.events.On(newEvent(eventName, api.Warning, "No resource found to remove"))
			return nil
		}
		if err != nil {
			return err
		}
		nw := nwInspect.Network
		if len(nw.Containers) > 0 {
			s.events.On(newEvent(eventName, api.Warning, "Resource is still in use"))
			found++
			continue
		}

		if _, err := s.apiClient().NetworkRemove(ctx, net.ID, client.NetworkRemoveOptions{}); err != nil {
			if errdefs.IsNotFound(err) {
				continue
			}
			s.events.On(errorEvent(eventName, err.Error()))
			return fmt.Errorf("failed to remove network %s: %w", name, err)
		}
		s.events.On(removedEvent(eventName))
		found++
	}

	if found == 0 {
		// in practice, it's extremely unlikely for this to ever occur, as it'd
		// mean the network was present when we queried at the start of this
		// method but was then deleted by something else in the interim
		s.events.On(newEvent(eventName, api.Warning, "No resource found to remove"))
		return nil
	}
	return nil
}

func (s *composeService) removeVolume(ctx context.Context, id string) error {
	resource := fmt.Sprintf("Volume %s", id)

View on GitHub (pinned to ddc4b044b6)

Solutions

1. Detach/stop remaining endpoints: docker network inspect <net> to find containers, then docker rm -f them, and re-run down
2. If the wrapped error is permission-related, run with correct user/context
3. docker network rm <id> manually to see the daemon's full error
4. Re-run docker compose down — removal is retried and NotFound is tolerated

// ensure no endpoints remain before down
nw, _ := cli.NetworkInspect(ctx, netName, client.NetworkInspectOptions{})
if len(nw.Containers) > 0 {
    for id := range nw.Containers { _ = cli.ContainerRemove(ctx, id, client.ContainerRemoveOptions{Force: true}) }
}

if err := compose.Down(...); err != nil {
    if strings.Contains(err.Error(), "failed to remove network") {
        // inspect endpoints, force-remove containers, retry down once
    }
    return err
}

When it happens

Trigger: removeNetwork loop calling NetworkRemove(net.ID) and getting e.g. an authorization error, 'network has active endpoints' variants surfaced as errors, or daemon internal failure during 'docker compose down'.

Common situations: Endpoints attached between the inspect and the remove (race); rootless/permission mismatch; overlay driver issues on Swarm nodes; daemon degraded mid-teardown.

Related errors

• failed to list networks: %w
• failed to create 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/006c55a35aaf6c7b. Report an issue: GitHub.