{"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/e9452d6e785f6e365712b9d71bd7517591773c86/cli/command/container/opts.go#L850-L886","documentation":"Raised in parseNetworkAttachmentOpt (opts.go:867-869) when per-network links are specified for a non-user-defined network mode (host, none, container:<id>, or built-in modes other than the legacy default-bridge --link path). In the advanced notation, link= is an endpoint option that creates an alias, which only user-defined networks support.","triggerScenarios":"Advanced syntax like `--network name=host,link=db` or `--network name=none,link=db`, or an endpoint whose Target fails IsUserDefined() while ep.Links is non-empty.","commonSituations":"Porting legacy --link usage into the advanced --network notation while still targeting a built-in network mode; assuming links work under host networking.","solutions":["Attach to a user-defined network: docker network create appnet; docker run --network name=appnet,link=db:db ...","Replace links with network aliases plus built-in DNS on a user-defined network (links are legacy)","Remove link= entirely if using host/none/container network modes — connect via localhost or the shared namespace instead"],"exampleFix":"// before\ndocker run --network name=host,link=db nginx\n// after\ndocker network create appnet\ndocker run --network name=appnet,link=db nginx","handlingStrategy":null,"validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":[],"tags":["docker-cli","network","links","user-defined-network"],"analyzedSha":"e9452d6e785f6e365712b9d71bd7517591773c86","analyzedAt":"2026-08-01T07:09:22.474Z","schemaVersion":2}