{"record":{"id":"112a81c5c916a1ed","repo":"nektos/act","slug":"network-scoped-aliases-are-only-supported-for-user","errorCode":null,"errorMessage":"network-scoped aliases are only supported for user-defined networks","messagePattern":"network-scoped aliases are only supported for user-defined networks","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/container/docker_cli.go","lineNumber":872,"sourceCode":"\t\t\tn.IPv6Address = ipv6\n\t\t}\n\t}\n\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 {","sourceCodeStart":854,"sourceCodeEnd":890,"githubUrl":"https://github.com/nektos/act/blob/4f411281417e88660bea1c1a1749aa71ae0bd60f/pkg/container/docker_cli.go#L854-L890","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"# before\njobs:\n  test:\n    runs-on: ubuntu-latest\n    container:\n      image: node:20\n      options: --network host:nodeapp\n\n# after\njobs:\n  test:\n    runs-on: ubuntu-latest\n    container:\n      image: node:20\n      options: --network host","handlingStrategy":"validation","validationCode":"// Validate container options before running act\npackage main\n\nimport (\n\t\"fmt\"\n\t\"strings\"\n)\n\nvar builtinNetworks = map[string]bool{\"default\": true, \"none\": true, \"bridge\": true, \"host\": true}\n\nfunc validateNetworkOptions(options string) error {\n\tfor _, flag := range strings.Fields(options) {\n\t\tif strings.HasPrefix(flag, \"--network=\") {\n\t\t\tflag = strings.TrimPrefix(flag, \"--network=\")\n\t\t}\n\t\tif !strings.HasPrefix(flag, \"--network\") {\n\t\t\tcontinue\n\t\t}\n\t\tvalue := strings.TrimPrefix(strings.TrimSpace(strings.TrimPrefix(flag, \"--network\")), \"=\")\n\t\tif target, _, found := strings.Cut(value, \":.\"); found && builtinNetworks[target] {\n\t\t\treturn fmt.Errorf(\"network %q is built-in; aliases are only allowed on user-defined networks\", target)\n\t\t}\n\t}\n\treturn nil\n}","typeGuard":null,"tryCatchPattern":"if err := runner.New(runner.Config{...}).NewRunExecutor(plan)(ctx); err != nil {\n    if strings.Contains(err.Error(), \"network-scoped aliases are only supported\") {\n        log.Warn(\"container options pair a built-in network with an alias; strip the alias or create a user-defined network\")\n    }\n    return err\n}","preventionTips":["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):'."],"tags":["docker","network","container-options","configuration"],"backgroundTag":null,"analyzedSha":"4f411281417e88660bea1c1a1749aa71ae0bd60f","analyzedAt":"2026-08-15T09:19:46.307Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}