{"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/e9452d6e785f6e365712b9d71bd7517591773c86/cli/command/container/opts.go#L847-L883","documentation":"Raised in parseNetworkAttachmentOpt (opts.go:863-866) when network aliases are requested on a non-user-defined network mode (default bridge, host, none, container:<id>). Alias-based DNS resolution is implemented by the embedded DNS server, which only serves user-defined networks, so aliases on built-in modes would silently do nothing and are rejected.","triggerScenarios":"`docker run --network bridge --network-alias web ...`, `--network host` or `--network container:x` combined with --network-alias, or advanced syntax `--network name=bridge,alias=web` — IsUserDefined() is false while ep.Aliases is non-empty.","commonSituations":"Assuming the default bridge supports DNS aliases like compose networks do; omitting --network entirely (defaulting to bridge) while passing --network-alias; using host networking with aliases left over from a previous config.","solutions":["Create and use a user-defined network: docker network create appnet; docker run --network appnet --network-alias web ...","Remove --network-alias when running on bridge/host/none/container modes","In Compose, define a network in the networks: section instead of relying on the default bridge"],"exampleFix":"// before\ndocker run --network bridge --network-alias web nginx\n// after\ndocker network create appnet\ndocker run --network appnet --network-alias web nginx","handlingStrategy":null,"validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":[],"tags":["docker-cli","network","aliases","user-defined-network"],"analyzedSha":"e9452d6e785f6e365712b9d71bd7517591773c86","analyzedAt":"2026-08-01T07:09:22.474Z","schemaVersion":2}