{"record":{"id":"9f7c1041339ca6fe","repo":"docker/cli","slug":"network-q-is-declared-as-external-but-it-is-not","errorCode":null,"errorMessage":"network %q is declared as external, but it is not in the right scope: %q instead of \"swarm\"","messagePattern":"network %q is declared as external, but it is not in the right scope: %q instead of \"swarm\"","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cli/command/stack/deploy_composefile.go","lineNumber":104,"sourceCode":"\t}\n\treturn serviceNetworks\n}\n\nfunc validateExternalNetworks(ctx context.Context, apiClient client.NetworkAPIClient, externalNetworks []string) error {\n\tfor _, networkName := range externalNetworks {\n\t\tif !container.NetworkMode(networkName).IsUserDefined() {\n\t\t\t// Networks that are not user defined always exist on all nodes as\n\t\t\t// local-scoped networks, so there's no need to inspect them.\n\t\t\tcontinue\n\t\t}\n\t\tres, err := apiClient.NetworkInspect(ctx, networkName, client.NetworkInspectOptions{})\n\t\tswitch {\n\t\tcase errdefs.IsNotFound(err):\n\t\t\treturn fmt.Errorf(\"network %q is declared as external, but could not be found. You need to create a swarm-scoped network before the stack is deployed\", networkName)\n\t\tcase err != nil:\n\t\t\treturn err\n\t\tcase res.Network.Scope != \"swarm\":\n\t\t\treturn fmt.Errorf(\"network %q is declared as external, but it is not in the right scope: %q instead of \\\"swarm\\\"\", networkName, res.Network.Scope)\n\t\t}\n\t}\n\treturn nil\n}\n\nfunc createSecrets(ctx context.Context, dockerCLI command.Cli, secrets []swarm.SecretSpec) error {\n\tapiClient := dockerCLI.Client()\n\n\tfor _, secretSpec := range secrets {\n\t\tres, err := apiClient.SecretInspect(ctx, secretSpec.Name, client.SecretInspectOptions{})\n\t\tswitch {\n\t\tcase err == nil:\n\t\t\t// secret already exists, then we update that\n\t\t\t_, err := apiClient.SecretUpdate(ctx, res.Secret.ID, client.SecretUpdateOptions{\n\t\t\t\tVersion: res.Secret.Meta.Version,\n\t\t\t\tSpec:    secretSpec,\n\t\t\t})\n\t\t\tif err != nil {","sourceCodeStart":86,"sourceCodeEnd":122,"githubUrl":"https://github.com/docker/cli/blob/4f84911bfe8811e9b028e4b1fee8e7510be79387/cli/command/stack/deploy_composefile.go#L86-L122","documentation":"Raised by validateExternalNetworks when an external network exists but its Scope is not 'swarm' (typically it is 'local', e.g. a bridge or host network). Swarm services can only attach to swarm-scoped (overlay) networks, so a local-scoped network is rejected even though it exists.","triggerScenarios":"Declaring `networks: { foo: { external: true } }` where 'foo' was created with a local-scope driver (bridge, host, macvlan in local scope, or default bridge). NetworkInspect succeeds (deploy_composefile.go:97) but res.Network.Scope != \"swarm\" at line 103.","commonSituations":"Creating the network with `docker network create foo` (defaults to bridge/local) instead of `-d overlay`; reusing a network built for non-Swarm compose; a network created by `docker-compose` (local) being referenced from a Swarm stack.","solutions":["Recreate the network as overlay (swarm-scoped): `docker network rm foo && docker network create -d overlay foo`.","Use a swarm-scoped driver like overlay for any network referenced by Swarm services.","Verify scope before deploy: `docker network inspect foo --format '{{.Scope}}'` should print 'swarm'."],"exampleFix":"# before\ndocker network create shared        # creates local bridge\n# after\ndocker network create -d overlay shared  # creates swarm-scoped overlay","handlingStrategy":"validation","validationCode":"// Verify scope of each external network before deploy\nfor _, name := range externalNetworks {\n    res, err := c.NetworkInspect(ctx, name, client.NetworkInspectOptions{})\n    if err != nil { return err }\n    if res.Network.Scope != \"swarm\" {\n        return fmt.Errorf(\"network %q scope %q; recreate as overlay\", name, res.Network.Scope)\n    }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always create shared networks with `-d overlay`.","Add a CI gate that inspects external network scopes before stack deploy.","Avoid referencing host/bridge networks from Swarm stacks."],"tags":["docker","stack","network","external","swarm","scope"],"backgroundTag":null,"analyzedSha":"4f84911bfe8811e9b028e4b1fee8e7510be79387","analyzedAt":"2026-08-07T12:15:29.814Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}