{"record":{"id":"cb8b63bac5de91cd","repo":"docker/compose","slug":"network-s-declared-as-external-but-could-not-be","errorCode":null,"errorMessage":"network %s declared as external, but could not be found","messagePattern":"network (.+?) declared as external, but could not be found","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/compose/create.go","lineNumber":1493,"sourceCode":"\t\treturn net.Name != n.Name && net.ID != n.Name\n\t})\n\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,","sourceCodeStart":1475,"sourceCodeEnd":1511,"githubUrl":"https://github.com/docker/compose/blob/ddc4b044b62e9f715212ea4143fa830fac76382f/pkg/compose/create.go#L1475-L1511","documentation":"A network is marked 'external: true' in the compose file, but NetworkList with an exact name filter finds zero matches and the engine is not in Swarm mode, so compose cannot attach to it. On Swarm-enabled hosts compose defers the check because overlay networks may not be registered on every node.","triggerScenarios":"networks: {mynet: {external: true}} where no Docker network with exactly that name exists; typical during 'up' when resolving external networks via resolveExternalNetwork.","commonSituations":"Forgot to create the network beforehand (docker network create mynet); typo in the network name; running on a different engine/context than where the network lives; network removed by prune.","solutions":["Create it first: docker network create mynet (or the shared network e.g. for traefik/proxy)","Fix the name in the compose file to match the existing network","If compose should manage it, remove 'external: true'","Verify you are on the right docker context: docker context show && docker network ls"],"exampleFix":"# before\nnetworks:\n  proxy:\n    external: true\n# after (let compose own it)\nnetworks:\n  proxy: {}","handlingStrategy":"validation","validationCode":"// exact-name existence check before up\nres, err := cli.NetworkList(ctx, client.NetworkListOptions{\n    Filters: client.Filters{\"name\": {n.Name}},\n})\nif err != nil { return err }\nif len(res.Items) == 0 { return fmt.Errorf(\"create network %s first\", n.Name) }","typeGuard":null,"tryCatchPattern":"if err := compose.Up(...); err != nil && strings.Contains(err.Error(), \"declared as external, but could not be found\") {\n    _ = cli.NetworkCreate(ctx, n.Name, client.NetworkCreateOptions{CheckDuplicate: true})\n    err = compose.Up(...)\n}","preventionTips":["Create shared networks in a bootstrap step before compose up","Automate network creation in CI scripts","Double-check docker context before depending on host-local networks"],"tags":["network","external-resources","compose-file"],"backgroundTag":null,"analyzedSha":"ddc4b044b62e9f715212ea4143fa830fac76382f","analyzedAt":"2026-08-15T13:31:42.319Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}