{"record":{"id":"51490a738334547e","repo":"docker/cli","slug":"links-are-only-supported-for-user-defined-networks","errorCode":null,"errorMessage":"links are only supported for user-defined networks","messagePattern":"links are only supported for user-defined networks","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cli/command/container/opts.go","lineNumber":868,"sourceCode":"\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 {\n\t\tepConfig.IPAMConfig = &network.EndpointIPAMConfig{\n\t\t\tIPv4Address:  ep.IPv4Address,\n\t\t\tIPv6Address:  ep.IPv6Address,","sourceCodeStart":850,"sourceCodeEnd":886,"githubUrl":"https://github.com/docker/cli/blob/4f84911bfe8811e9b028e4b1fee8e7510be79387/cli/command/container/opts.go#L850-L886","documentation":"Thrown by parseNetworkAttachmentOpt when links are supplied for a non-user-defined network. Legacy --link semantics (name aliasing) only work on user-defined networks in the modern code path; the default bridge uses legacy links differently and host/none/container: do not support them at all, so the CLI rejects the combination early.","triggerScenarios":"`docker run --network host --link foo:bar alpine` or `--network none --link foo`. Also via advanced notation `--network host:link=foo:bar`. The IsUserDefined() check at opts.go:863 returns false and ep.Links is non-empty.","commonSituations":"Migrating from default-bridge --link usage to host networking while keeping the --link flag. Misconfigured compose that pairs links with external/host networks. Stale legacy scripts after switching network modes.","solutions":["Move the linked containers onto a user-defined network where DNS service discovery replaces --link entirely.","If staying on host/none, remove the --link flags and use direct hostnames/IPs.","On the default bridge, only legacy links are supported; switch to a user-defined bridge to use the modern link semantics."],"exampleFix":"// before\ndocker run --network host --link db:db alpine\n\n// after\ndocker network create appnet\ndocker run --network appnet --link db:db alpine","handlingStrategy":"validation","validationCode":"func linksAllowed(networkMode string) bool {\n    return container.NetworkMode(networkMode).IsUserDefined()\n}\n\nfor net, links := range desiredLinks {\n    if len(links) > 0 && !linksAllowed(net) {\n        return fmt.Errorf(\"links are only supported for user-defined networks: %s\", net)\n    }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Migrate --link usage to user-defined network DNS service discovery.","When changing network_mode, audit and remove --link flags that no longer apply.","Prefer --network-alias on a user-defined bridge over legacy links."],"tags":["network","links","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"}