invalid option ' ' in ' ': option should not have whitespace

Error message

invalid option '%s' in '%s': option should not have whitespace

What it means

Returned by MountOpt.Set (opts/mount.go:43) when a mount option key has leading or trailing whitespace. After splitting a CSV field on '=', the code compares the raw key against its TrimSpace'd form; any difference (spaces/tabs around the key) is rejected because option keys must be clean identifiers.

Solutions

Remove all whitespace around option keys: type=volume,source=foo.
Do not pad after commas; the CSV parser keeps those spaces as part of the next key.
If you need spaces in a value, wrap the whole --mount argument in quotes but keep keys unspaced.
Check for stray tabs/copied non-breaking spaces from documentation.

Example fix

// before
--mount "type=volume, source=mydata, target=/data"

// after
--mount "type=volume,source=mydata,target=/data"

Defensive patterns

Strategy: validation

Validate before calling

// sanitizeMountSpec trims field separators so keys stay clean for MountOpt.Set.
func sanitizeMountSpec(spec string) (string, error) {
    r := csv.NewReader(strings.NewReader(spec))
    fields, err := r.Read()
    if err != nil {
        return "", err
    }
    for _, f := range fields {
        key, _, _ := strings.Cut(f, "=")
        if strings.TrimSpace(key) != key {
            return "", fmt.Errorf("key %q has surrounding whitespace", key)
        }
    }
    return spec, nil
}

Try / catch

var m opts.MountOpt
if err := m.Set(spec); err != nil {
    return fmt.Errorf("invalid mount %q: %w", spec, err)
}

Prevention

Never pad after commas in --mount CSV.
Generate mount strings from a typed struct rather than concatenation.
Lint mount specs in CI for whitespace around keys.

When it happens

Trigger: Passing a `--mount` CSV like `type=volume, source=foo` (space after comma), `src =foo`, or `\ttype=volume`. The csv.Reader preserves intra-field whitespace, so ` src=foo` yields key ` src` which fails the equality check.

Common situations: Adding spaces after commas for readability in shell/compose, tabs from a pasted snippet, or trailing whitespace inside a quoted CSV field.

Related errors

AI-assisted analysis of docker/cli@4f84911bfe (2026-08-07). Data as JSON: /api/errors/6cb8257839119508. Report an issue: GitHub.

Appendix: source

Thrown at opts/mount.go:43

	value = strings.TrimSpace(value)
	if value == "" {
		return errors.New("value is empty")
	}

	csvReader := csv.NewReader(strings.NewReader(value))
	fields, err := csvReader.Read()
	if err != nil {
		return err
	}

	mount := mounttypes.Mount{
		Type: mounttypes.TypeVolume, // default to volume mounts
	}

	for _, field := range fields {
		key, val, hasValue := strings.Cut(field, "=")
		if k := strings.TrimSpace(key); k != key {
			return fmt.Errorf("invalid option '%s' in '%s': option should not have whitespace", k, field)
		}
		if hasValue {
			v := strings.TrimSpace(val)
			if v == "" {
				return fmt.Errorf("invalid value for '%s': value is empty", key)
			}
			if v != val {
				return fmt.Errorf("invalid value for '%s' in '%s': value should not have whitespace", key, field)
			}
		}

		// TODO(thaJeztah): these options should not be case-insensitive.
		key = strings.ToLower(key)

		if !hasValue {
			switch key {
			case "readonly", "ro", "volume-nocopy", "bind-nonrecursive", "bind-create-src":
				// boolean values

View on GitHub (pinned to 4f84911bfe)