docker/compose · error

failed to create network %s: %w

Error message

failed to create network %s: %w

What it means

Wraps any non-conflict failure from the Docker Engine's NetworkCreate call while provisioning a compose network. Conflict (name already taken by a concurrent compose run) is deliberately treated as success; everything else — bad driver, invalid IPAM, name/label policy violations, daemon issues — is surfaced with the network name.

Source

Thrown at pkg/compose/create.go:1442

			return err
		}
		createOpts.IPAM.Config = append(createOpts.IPAM.Config, c)
	}

	networkEventName := fmt.Sprintf("Network %s", n.Name)
	s.events.On(creatingEvent(networkEventName))

	if _, err := s.apiClient().NetworkCreate(ctx, n.Name, createOpts); err != nil {
		// A concurrent `docker compose up|run` may have created the same network
		// between the observed-state snapshot and now. Treat the resulting
		// conflict as success rather than failing hard, mirroring the retry the
		// previous ensureNetwork performed.
		if errdefs.IsConflict(err) {
			s.events.On(createdEvent(networkEventName))
			return nil
		}
		s.events.On(errorEvent(networkEventName, err.Error()))
		return fmt.Errorf("failed to create network %s: %w", n.Name, err)
	}
	s.events.On(createdEvent(networkEventName))
	return nil
}

func (s *composeService) resolveExternalNetwork(ctx context.Context, n *types.NetworkConfig) (string, error) {
	// NetworkInspect will match on ID prefix, so NetworkList with a name
	// filter is used to look for an exact match to prevent e.g. a network
	// named `db` from getting erroneously matched to a network with an ID
	// like `db9086999caf`
	res, err := s.apiClient().NetworkList(ctx, client.NetworkListOptions{
		Filters: make(client.Filters).Add("name", n.Name),
	})
	if err != nil {
		return "", err
	}
	networks := res.Items

View on GitHub (pinned to ddc4b044b6)

Solutions

1. Read the wrapped daemon message — it names the real cause (pool overlap, driver, etc.)
2. Prune stale networks (docker network prune) or configure default-address-pools to widen/segment subnets
3. Install/verify the network driver plugin if a custom driver is used
4. Retry 'docker compose up' if the daemon was restarting

// pre-check the planned subnet doesn't overlap existing networks
nets, _ := cli.NetworkList(ctx, client.NetworkListOptions{})
planned := netip.MustParsePrefix("172.30.0.0/16")
for _, n := range nets.Items {
    for _, c := range n.IPAM.Config {
        if p, err := netip.ParsePrefix(c.Subnet); err == nil && p.Overlaps(planned) {
            return fmt.Errorf("subnet %s overlaps network %s", planned, n.Name)
        }
    }
}

// retry once on transient transport errors, otherwise surface daemon cause
for attempt := 0; attempt < 2; attempt++ {
    if err := compose.Up(ctx, api.UpOptions{...}); err != nil {
        if errdefs.IsUnavailable(err) || errdefs.IsSystem(err) { time.Sleep(time.Second); continue }
        return err
    }
    break
}

When it happens

Trigger: ensureNetwork -> NetworkCreate returning an error that is not errdefs.IsConflict: unknown network driver, overlapping subnet, invalid options/labels, daemon unreachable or authorization failure during 'docker compose up'.

Common situations: Subnet pool exhaustion (many compose projects on one host); custom driver plugin not installed; overlapping 172.x subnets; transient daemon restarts during up.

Related errors

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