{"record":{"id":"ab03c7554fc8a2d8","repo":"docker/compose","slug":"multiple-networks-with-name-q-were-found-use-net","errorCode":null,"errorMessage":"multiple networks with name %q were found. Use network ID as `name` to avoid ambiguity","messagePattern":"multiple networks with name %q were found\\. Use network ID as `name` to avoid ambiguity","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/compose/create.go","lineNumber":1495,"sourceCode":"\n\tswitch len(networks) {\n\tcase 1:\n\t\treturn networks[0].ID, nil\n\tcase 0:\n\t\tenabled, err := s.isSwarmEnabled(ctx)\n\t\tif err != nil {\n\t\t\treturn \"\", err\n\t\t}\n\t\tif enabled {\n\t\t\t// Swarm nodes do not register overlay networks that were\n\t\t\t// created on a different node unless they're in use.\n\t\t\t// So we can't preemptively check network exists, but\n\t\t\t// networkAttach will later fail anyway if network actually doesn't exist\n\t\t\treturn \"swarm\", nil\n\t\t}\n\t\treturn \"\", fmt.Errorf(\"network %s declared as external, but could not be found\", n.Name)\n\tdefault:\n\t\treturn \"\", fmt.Errorf(\"multiple networks with name %q were found. Use network ID as `name` to avoid ambiguity\", n.Name)\n\t}\n}\n\nfunc (s *composeService) createVolume(ctx context.Context, volume types.VolumeConfig) error {\n\teventName := fmt.Sprintf(\"Volume %s\", volume.Name)\n\ts.events.On(creatingEvent(eventName))\n\thash, err := VolumeHash(volume)\n\tif err != nil {\n\t\treturn err\n\t}\n\tvolume.CustomLabels = volume.CustomLabels.Add(api.ConfigHashLabel, hash)\n\t_, err = s.apiClient().VolumeCreate(ctx, client.VolumeCreateOptions{\n\t\tLabels:     mergeLabels(volume.Labels, volume.CustomLabels),\n\t\tName:       volume.Name,\n\t\tDriver:     volume.Driver,\n\t\tDriverOpts: volume.DriverOpts,\n\t})\n\tif err != nil {","sourceCodeStart":1477,"sourceCodeEnd":1513,"githubUrl":"https://github.com/docker/compose/blob/ddc4b044b62e9f715212ea4143fa830fac76382f/pkg/compose/create.go#L1477-L1513","documentation":"NetworkList by name returned more than one network, so the external network reference is ambiguous — Docker name filters are substring-based, and multiple networks (e.g. 'db' and 'db2', or duplicates across projects) can match. Compose refuses to guess and asks for the network ID.","triggerScenarios":"networks: {name: X, external: true} where two or more networks have X as a name-prefix match during resolveExternalNetwork (switch case len(networks) > 1).","commonSituations":"Short network name that is a prefix of other names ('web' vs 'web_default'); duplicate networks created by repeated runs or manual creation; shared host with many projects.","solutions":["Set the external network's 'name:' to the full network ID from docker network ls --no-trunc","Alternatively delete the duplicate networks so exactly one remains","Use a longer, unique network name"],"exampleFix":"# before\nnetworks:\n  default:\n    name: db\n    external: true\n# after\nnetworks:\n  default:\n    name: 6c5f2d1e9a3b  # network ID from `docker network ls`\n    external: true","handlingStrategy":"validation","validationCode":"res, _ := cli.NetworkList(ctx, client.NetworkListOptions{Filters: client.Filters{\"name\": {n.Name}}})\nvar exact []string\nfor _, net := range res.Items { if net.Name == n.Name { exact = append(exact, net.ID) } }\nif len(exact) != 1 { return fmt.Errorf(\"need exactly 1 network named %s, got %d; use ID\", n.Name, len(exact)) }","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Reference external networks by ID in generated compose files","Name shared networks distinctively (project-proxy-net, not proxy)","Periodically prune duplicate networks"],"tags":["network","ambiguity","external-resources"],"backgroundTag":null,"analyzedSha":"ddc4b044b62e9f715212ea4143fa830fac76382f","analyzedAt":"2026-08-15T13:31:42.319Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}