{"record":{"id":"aa72a939cbef768f","repo":"docker/cli","slug":"network-scoped-aliases-are-only-supported-for-user","errorCode":null,"errorMessage":"network-scoped aliases are only supported for user-defined networks","messagePattern":"network-scoped aliases are only supported for user-defined networks","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cli/command/container/opts.go","lineNumber":865,"sourceCode":"\t\t\tn.IPv6Address = ipv6\n\t\t}\n\t}\n\tif copts.macAddress != \"\" {\n\t\tn.MacAddress = copts.macAddress\n\t}\n\tif copts.linkLocalIPs.Len() > 0 {\n\t\tn.LinkLocalIPs = toNetipAddrSlice(copts.linkLocalIPs.GetSlice())\n\t}\n\treturn nil\n}\n\nfunc parseNetworkAttachmentOpt(ep opts.NetworkAttachmentOpts) (*network.EndpointSettings, error) {\n\tif strings.TrimSpace(ep.Target) == \"\" {\n\t\treturn nil, errors.New(\"no name set for network\")\n\t}\n\tif !container.NetworkMode(ep.Target).IsUserDefined() {\n\t\tif len(ep.Aliases) > 0 {\n\t\t\treturn nil, errors.New(\"network-scoped aliases are only supported for user-defined networks\")\n\t\t}\n\t\tif len(ep.Links) > 0 {\n\t\t\treturn nil, errors.New(\"links are only supported for user-defined networks\")\n\t\t}\n\t}\n\n\tepConfig := &network.EndpointSettings{\n\t\tGwPriority: ep.GwPriority,\n\t}\n\tepConfig.Aliases = append(epConfig.Aliases, ep.Aliases...)\n\tif len(ep.DriverOpts) > 0 {\n\t\tepConfig.DriverOpts = make(map[string]string)\n\t\tepConfig.DriverOpts = ep.DriverOpts\n\t}\n\tif len(ep.Links) > 0 {\n\t\tepConfig.Links = ep.Links\n\t}\n\tif ep.IPv4Address.IsValid() || ep.IPv6Address.IsValid() || len(ep.LinkLocalIPs) > 0 {","sourceCodeStart":847,"sourceCodeEnd":883,"githubUrl":"https://github.com/docker/cli/blob/4f84911bfe8811e9b028e4b1fee8e7510be79387/cli/command/container/opts.go#L847-L883","documentation":"Thrown by parseNetworkAttachmentOpt when network-scoped aliases are supplied for a network that is not user-defined. The default bridge, host, none, and container: modes do not implement DNS-based alias resolution, so Docker rejects aliases there. container.NetworkMode(ep.Target).IsUserDefined() returns false for those built-in modes.","triggerScenarios":"Using advanced notation aliases on a built-in: `docker run --network bridge:alias=web ...`, or `--network host:alias=web`. Also triggered programmatically by setting EndpointSettings.Aliases against the default bridge.","commonSituations":"Treating the default bridge like a user-defined network (it lacks automatic DNS). Forgetting to create a custom network first: `docker network create mynet` then attaching aliases there. Copying compose alias config onto a host/bridge setup.","solutions":["Create and use a user-defined network: `docker network create mynet` then `docker run --network mynet:alias=web ...`.","If you must use the default bridge, drop the alias and rely on legacy --link for name resolution instead.","Switch host/none/container: modes to a user-defined bridge network if aliases are required."],"exampleFix":"// before\ndocker run --network bridge --network-alias web alpine\n\n// after\ndocker network create mynet\ndocker run --network mynet --network-alias web alpine","handlingStrategy":"validation","validationCode":"// Ensure aliases are only attached to user-defined networks before run.\nfunc aliasesAllowed(networkMode string) bool {\n    return container.NetworkMode(networkMode).IsUserDefined()\n}\n\nfor net, aliases := range desiredAliases {\n    if len(aliases) > 0 && !aliasesAllowed(net) {\n        return fmt.Errorf(\"network-scoped aliases are only supported for user-defined networks: %s\", net)\n    }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always create a user-defined network (`docker network create`) before relying on aliases.","Never assume the default bridge resolves aliases — it does not without legacy links.","In compose, declare networks: as user-defined bridges; avoid aliasing on network_mode: host/bridge."],"tags":["network","aliases","user-defined-network","container"],"backgroundTag":null,"analyzedSha":"4f84911bfe8811e9b028e4b1fee8e7510be79387","analyzedAt":"2026-08-07T12:15:29.814Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}