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

Error message

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

What it means

Thrown by parseNetworkAttachmentOpt when network-scoped aliases are supplied for a network that is not user-defined. The default bridge, host, none, and container: modes do not implement DNS-based alias resolution, so Docker rejects aliases there. container.NetworkMode(ep.Target).IsUserDefined() returns false for those built-in modes.

Solutions

Create and use a user-defined network: `docker network create mynet` then `docker run --network mynet:alias=web ...`.
If you must use the default bridge, drop the alias and rely on legacy --link for name resolution instead.
Switch host/none/container: modes to a user-defined bridge network if aliases are required.

Example fix

// before
docker run --network bridge --network-alias web alpine

// after
docker network create mynet
docker run --network mynet --network-alias web alpine

Defensive patterns

Strategy: validation

Validate before calling

// Ensure aliases are only attached to user-defined networks before run.
func aliasesAllowed(networkMode string) bool {
    return container.NetworkMode(networkMode).IsUserDefined()
}

for net, aliases := range desiredAliases {
    if len(aliases) > 0 && !aliasesAllowed(net) {
        return fmt.Errorf("network-scoped aliases are only supported for user-defined networks: %s", net)
    }
}

Prevention

Always create a user-defined network (`docker network create`) before relying on aliases.
Never assume the default bridge resolves aliases — it does not without legacy links.
In compose, declare networks: as user-defined bridges; avoid aliasing on network_mode: host/bridge.

When it happens

Trigger: Using advanced notation aliases on a built-in: `docker run --network bridge:alias=web ...`, or `--network host:alias=web`. Also triggered programmatically by setting EndpointSettings.Aliases against the default bridge.

Common situations: Treating the default bridge like a user-defined network (it lacks automatic DNS). Forgetting to create a custom network first: `docker network create mynet` then attaching aliases there. Copying compose alias config onto a host/bridge setup.

Related errors

AI-assisted analysis of docker/cli@4f84911bfe (2026-08-07). Data as JSON: /api/errors/aa72a939cbef768f. Report an issue: GitHub.

Appendix: 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 4f84911bfe)