docker/cli · error

network-scoped aliases are only supported for user-defined n

Error message

network-scoped aliases are only supported for user-defined networks

What it means

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.

Source

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

			n.IPv6Address = ipv6
		}
	}
	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 {

View on GitHub (pinned to e9452d6e78)

Solutions

1. Create and use a user-defined network: docker network create appnet; docker run --network appnet --network-alias web ...
2. Remove --network-alias when running on bridge/host/none/container modes
3. In Compose, define a network in the networks: section instead of relying on the default bridge

Example fix

// before
docker run --network bridge --network-alias web nginx
// after
docker network create appnet
docker run --network appnet --network-alias web nginx

When it happens

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

Common situations: 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.

Related errors

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

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