nektos/act · error

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

Error message

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

What it means

mergeContainerConfigs parses the job's container options string with shellquote.Split before feeding them to a pflag FlagSet. If shell-style tokenization fails — unbalanced quotes or backslashes — the options cannot even be split into arguments and this error names the raw option string.

Source

Thrown at pkg/container/docker_run.go:368

		return nil
	}
}

func (cr *containerReference) mergeContainerConfigs(ctx context.Context, config *container.Config, hostConfig *container.HostConfig) (*container.Config, *container.HostConfig, error) {
	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)
	}

View on GitHub (pinned to 4f41128141)

Solutions

1. Balance all quotes in the options string; prefer single-word values that need no quoting
2. Test tokenization locally: echo <options> | xargs -n1 echo (or shellquote in Go)
3. Simplify: move complex settings into act flags (--container-options) or dedicated workflow fields where available

Example fix

# before
container:
  image: node:20
  options: --shm-size="1g

# after
container:
  image: node:20
  options: --shm-size=1g

# shell: verify the options string tokenizes cleanly
printf '%s' "$OPTIONS" | xargs -n1 echo >/dev/null || echo "unbalanced quoting in options"

When it happens

Trigger: A container: options: value (or --container-options flag) with an unterminated single/double quote, trailing backslash, or otherwise invalid shell quoting, e.g. options: --cpus 2=" or --shm-size="1g.

Common situations: Hand-writing YAML options lines and losing a closing quote; escaping rules differ between YAML, shell, and pflag so a value that worked in docker run CLI breaks when embedded in the workflow.

Related errors

• Cannot parse 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/4c18a356b55f8ad2. Report an issue: GitHub.