nektos/act · error

Cannot parse container options

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.

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
• Cannot merge container.Config options
• Cannot process container options
• compacting json for seccomp profile
• invalid device cgroup format

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

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