{"record":{"id":"f32812182577c37a","repo":"docker/compose","slug":"failed-to-create-network-s-w","errorCode":null,"errorMessage":"failed to create network %s: %w","messagePattern":"failed to create network (.+?): %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/compose/create.go","lineNumber":1442,"sourceCode":"\t\t\treturn err\n\t\t}\n\t\tcreateOpts.IPAM.Config = append(createOpts.IPAM.Config, c)\n\t}\n\n\tnetworkEventName := fmt.Sprintf(\"Network %s\", n.Name)\n\ts.events.On(creatingEvent(networkEventName))\n\n\tif _, err := s.apiClient().NetworkCreate(ctx, n.Name, createOpts); err != nil {\n\t\t// A concurrent `docker compose up|run` may have created the same network\n\t\t// between the observed-state snapshot and now. Treat the resulting\n\t\t// conflict as success rather than failing hard, mirroring the retry the\n\t\t// previous ensureNetwork performed.\n\t\tif errdefs.IsConflict(err) {\n\t\t\ts.events.On(createdEvent(networkEventName))\n\t\t\treturn nil\n\t\t}\n\t\ts.events.On(errorEvent(networkEventName, err.Error()))\n\t\treturn fmt.Errorf(\"failed to create network %s: %w\", n.Name, err)\n\t}\n\ts.events.On(createdEvent(networkEventName))\n\treturn nil\n}\n\nfunc (s *composeService) resolveExternalNetwork(ctx context.Context, n *types.NetworkConfig) (string, error) {\n\t// NetworkInspect will match on ID prefix, so NetworkList with a name\n\t// filter is used to look for an exact match to prevent e.g. a network\n\t// named `db` from getting erroneously matched to a network with an ID\n\t// like `db9086999caf`\n\tres, err := s.apiClient().NetworkList(ctx, client.NetworkListOptions{\n\t\tFilters: make(client.Filters).Add(\"name\", n.Name),\n\t})\n\tif err != nil {\n\t\treturn \"\", err\n\t}\n\tnetworks := res.Items\n","sourceCodeStart":1424,"sourceCodeEnd":1460,"githubUrl":"https://github.com/docker/compose/blob/ddc4b044b62e9f715212ea4143fa830fac76382f/pkg/compose/create.go#L1424-L1460","documentation":"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.","triggerScenarios":"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'.","commonSituations":"Subnet pool exhaustion (many compose projects on one host); custom driver plugin not installed; overlapping 172.x subnets; transient daemon restarts during up.","solutions":["Read the wrapped daemon message — it names the real cause (pool overlap, driver, etc.)","Prune stale networks (docker network prune) or configure default-address-pools to widen/segment subnets","Install/verify the network driver plugin if a custom driver is used","Retry 'docker compose up' if the daemon was restarting"],"exampleFix":null,"handlingStrategy":"retry","validationCode":"// pre-check the planned subnet doesn't overlap existing networks\nnets, _ := cli.NetworkList(ctx, client.NetworkListOptions{})\nplanned := netip.MustParsePrefix(\"172.30.0.0/16\")\nfor _, n := range nets.Items {\n    for _, c := range n.IPAM.Config {\n        if p, err := netip.ParsePrefix(c.Subnet); err == nil && p.Overlaps(planned) {\n            return fmt.Errorf(\"subnet %s overlaps network %s\", planned, n.Name)\n        }\n    }\n}","typeGuard":null,"tryCatchPattern":"// retry once on transient transport errors, otherwise surface daemon cause\nfor attempt := 0; attempt < 2; attempt++ {\n    if err := compose.Up(ctx, api.UpOptions{...}); err != nil {\n        if errdefs.IsUnavailable(err) || errdefs.IsSystem(err) { time.Sleep(time.Second); continue }\n        return err\n    }\n    break\n}","preventionTips":["Configure daemon default-address-pools for many projects","Prune unused networks periodically","Validate driver availability before up"],"tags":["network","docker-api","subnet","retryable"],"backgroundTag":null,"analyzedSha":"ddc4b044b62e9f715212ea4143fa830fac76382f","analyzedAt":"2026-08-15T13:31:42.319Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}