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

Thrown by parseNetworkAttachmentOpt when a container options string specifies network-scoped aliases (--network name:alias[,alias]) for a network that Docker considers built-in rather than user-defined. Built-in network modes are 'default', 'none', 'bridge' (the predefined one), 'host', and slirp4netns-style modes; aliases only resolve inside networks created via 'docker network create'. The check uses container.NetworkMode(ep.Target).IsUserDefined(), which rejects exactly those reserved names.

Source

Thrown at pkg/container/docker_cli.go:872

			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 4f41128141)

Solutions

Remove the alias segment for built-in networks: use '--network host' instead of '--network host:myalias'.
If aliases are required, create a user-defined network and reference it: add a step or pre-hook running 'docker network create act-net' and set '--network act-net:myalias'.
If you rely on service discovery between the job container and services, keep act's default behavior (it already creates a user-defined network per run and assigns aliases) instead of overriding --network.
Check for duplicate/conflicting --network flags in the container options string; the last one wins and may carry the alias.

Example fix

# before
jobs:
  test:
    runs-on: ubuntu-latest
    container:
      image: node:20
      options: --network host:nodeapp

# after
jobs:
  test:
    runs-on: ubuntu-latest
    container:
      image: node:20
      options: --network host

Defensive patterns

Strategy: validation

Validate before calling

// Validate container options before running act
package main

import (
	"fmt"
	"strings"
)

var builtinNetworks = map[string]bool{"default": true, "none": true, "bridge": true, "host": true}

func validateNetworkOptions(options string) error {
	for _, flag := range strings.Fields(options) {
		if strings.HasPrefix(flag, "--network=") {
			flag = strings.TrimPrefix(flag, "--network=")
		}
		if !strings.HasPrefix(flag, "--network") {
			continue
		}
		value := strings.TrimPrefix(strings.TrimSpace(strings.TrimPrefix(flag, "--network")), "=")
		if target, _, found := strings.Cut(value, ":."); found && builtinNetworks[target] {
			return fmt.Errorf("network %q is built-in; aliases are only allowed on user-defined networks", target)
		}
	}
	return nil
}

Try / catch

if err := runner.New(runner.Config{...}).NewRunExecutor(plan)(ctx); err != nil {
    if strings.Contains(err.Error(), "network-scoped aliases are only supported") {
        log.Warn("container options pair a built-in network with an alias; strip the alias or create a user-defined network")
    }
    return err
}

Prevention

Never append ':alias' to built-in network names (host, bridge, none, default) in container options.
Create user-defined networks with 'docker network create' before using aliases in act options.
Lint workflow container.options lines in CI with a regex for '--network (host|bridge|none|default):'.

When it happens

Trigger: Running act with a job container options line such as 'options: --network bridge:myalias' or '--network host:myalias', or a services/job 'network' field that pairs a predefined network name with an alias segment. Any value where the target before the first colon is default/none/bridge/host/ns:/slirp4netns and the alias list is non-empty.

Common situations: Copying a docker run command like 'docker run --network host --network-alias foo' into a workflow's container options; assuming the default bridge supports aliases (it does not — DNS discovery only works on user-defined networks); leftover alias syntax when switching a workflow from a compose-defined network to 'host' networking for performance.

Related errors

AI-assisted analysis of nektos/act@4f41128141 (2026-08-15). Data as JSON: /api/errors/112a81c5c916a1ed. Report an issue: GitHub.