docker/cli · error

links are only supported for user-defined networks

Error message

links are only supported for user-defined networks

What it means

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.

Source

Thrown at cli/command/container/opts.go:868

	if copts.macAddress != "" {
		n.MacAddress = copts.macAddress
	}
	if copts.linkLocalIPs.Len() > 0 {
		n.LinkLocalIPs = toNetipAddrSlice(copts.linkLocalIPs.GetSlice())
	}
	return nil
}

func parseNetworkAttachmentOpt(ep opts.NetworkAttachmentOpts) (*network.EndpointSettings, error) {
	if strings.TrimSpace(ep.Target) == "" {
		return nil, errors.New("no name set for network")
	}
	if !container.NetworkMode(ep.Target).IsUserDefined() {
		if len(ep.Aliases) > 0 {
			return nil, errors.New("network-scoped aliases are only supported for user-defined networks")
		}
		if len(ep.Links) > 0 {
			return nil, errors.New("links are only supported for user-defined networks")
		}
	}

	epConfig := &network.EndpointSettings{
		GwPriority: ep.GwPriority,
	}
	epConfig.Aliases = append(epConfig.Aliases, ep.Aliases...)
	if len(ep.DriverOpts) > 0 {
		epConfig.DriverOpts = make(map[string]string)
		epConfig.DriverOpts = ep.DriverOpts
	}
	if len(ep.Links) > 0 {
		epConfig.Links = ep.Links
	}
	if ep.IPv4Address.IsValid() || ep.IPv6Address.IsValid() || len(ep.LinkLocalIPs) > 0 {
		epConfig.IPAMConfig = &network.EndpointIPAMConfig{
			IPv4Address:  ep.IPv4Address,
			IPv6Address:  ep.IPv6Address,

View on GitHub (pinned to e9452d6e78)

Solutions

1. Attach to a user-defined network: docker network create appnet; docker run --network name=appnet,link=db:db ...
2. Replace links with network aliases plus built-in DNS on a user-defined network (links are legacy)
3. Remove link= entirely if using host/none/container network modes — connect via localhost or the shared namespace instead

Example fix

// before
docker run --network name=host,link=db nginx
// after
docker network create appnet
docker run --network name=appnet,link=db nginx

When it happens

Trigger: 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.

Common situations: Porting legacy --link usage into the advanced --network notation while still targeting a built-in network mode; assuming links work under host networking.

Related errors

• conflicting options: cannot specify both --link and per-netw
• network-scoped aliases are only supported for user-defined n
• conflicting options: cannot attach both user-defined and non
• conflicting options: cannot specify both --network-alias and
• conflicting options: cannot specify both --ip and per-networ

AI-assisted analysis of docker/cli@e9452d6e78 (2026-08-01). Data as JSON: /data/errors/51490a738334547e.json. Report an issue: GitHub.