nektos/act · error

Cannot parse container options: '%s': '%w'

Error message

Cannot parse container options: '%s': '%w'

What it means

After shell-splitting succeeds, mergeContainerConfigs parses the option tokens with a pflag FlagSet (the docker-run-compatible flags registered by addFlags). Unknown flags, missing flag arguments, or malformed values make flags.Parse fail and produce 'Cannot parse container options' including the original string.

Source

Thrown at pkg/container/docker_run.go:373

	logger := common.Logger(ctx)
	input := cr.input

	if input.Options == "" {
		return config, hostConfig, nil
	}

	// parse configuration from CLI container.options
	flags := pflag.NewFlagSet("container_flags", pflag.ContinueOnError)
	copts := addFlags(flags)

	optionsArgs, err := shellquote.Split(input.Options)
	if err != nil {
		return nil, nil, fmt.Errorf("Cannot split container options: '%s': '%w'", input.Options, err)
	}

	err = flags.Parse(optionsArgs)
	if err != nil {
		return nil, nil, fmt.Errorf("Cannot parse container options: '%s': '%w'", input.Options, err)
	}

	if len(copts.netMode.Value()) == 0 {
		if err = copts.netMode.Set(cr.input.NetworkMode); err != nil {
			return nil, nil, fmt.Errorf("Cannot parse networkmode=%s. This is an internal error and should not happen: '%w'", cr.input.NetworkMode, err)
		}
	}

	containerConfig, err := parse(flags, copts, runtime.GOOS)
	if err != nil {
		return nil, nil, fmt.Errorf("Cannot process container options: '%s': '%w'", input.Options, err)
	}

	logger.Debugf("Custom container.Config from options ==> %+v", containerConfig.Config)

	err = mergo.Merge(config, containerConfig.Config, mergo.WithOverride)
	if err != nil {
		return nil, nil, fmt.Errorf("Cannot merge container.Config options: '%s': '%w'", input.Options, err)

View on GitHub (pinned to 4f41128141)

Solutions

1. Read the error detail: pflag reports the exact unknown/bad flag
2. Strip flags not needed for CI jobs (detached, tty, interactive) and keep resource/security opts
3. Check act's supported option flags (docker run-style: --cpus, --memory, --shm-size, --security-opt, --device, --volume, ...)
4. Update act — newer versions register more flags

Example fix

# before
options: --rm --name foo --cpus 2   # --rm/--name are managed by act itself

# after
options: --cpus 2

# shell: every token must be a known docker-run flag or a value
docker run --rm $OPTIONS alpine true  # cheapest oracle for flag validity

When it happens

Trigger: Passing a flag act's embedded docker-run parser does not know (e.g. --detach, --gpus on a build without it), a flag missing its value (--memory with nothing after it at end of string), or values of the wrong type for the flag.

Common situations: Copying a docker run command line into container.options without removing flags act's flag set lacks; using newer Docker CLI flags against an older act version.

Related errors

• Cannot split container options: '%s': '%w'
• network-scoped aliases are only supported for user-defined n
• invalid storage option
• valid streams are STDIN, STDOUT and STDERR
• %s is not a valid mac address

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