What causes "variable '%s' contains whitespaces" in docker/cli?

Remove all spaces/tabs from the key: 'MYVAR=value' and 'VAR=value' (no space before '=').

variable ' ' contains whitespaces

Error message

variable '%s' contains whitespaces

What it means

Returned inside parseKeyValueFile when the KEY portion (before '=') contains any whitespace (space or tab). kvfile trims leading whitespace from the line but then forbids internal/trailing whitespace in the key itself. Both 'MY VAR=x' and 'VAR =x' fail.

Solutions

Remove all spaces/tabs from the key: 'MYVAR=value' and 'VAR=value' (no space before '=').
Use underscores instead of spaces in variable names.
Turn on 'show whitespace' in your editor when editing env files.

Example fix

# before
MY VAR=value
VAR =value
# after
MY_VAR=value
VAR=value

Defensive patterns

Strategy: validation

Validate before calling

// Reject keys containing whitespace before kvfile.Parse.
import ("bufio"; "os"; "strings")

func noWhitespaceKeys(name string) error {
    f, err := os.Open(name)
    if err != nil { return err }
    defer f.Close()
    s := bufio.NewScanner(f)
    for ln := 1; s.Scan(); ln++ {
        t := strings.TrimLeft(s.Text(), " \t")
        if t == "" || strings.HasPrefix(t, "#") { continue }
        key, _, _ := strings.Cut(t, "=")
        if strings.ContainsAny(key, " \t") {
            return fmt.Errorf("%s:%d: key %q contains whitespace", name, ln, key)
        }
    }
    return s.Err()
}

// if err := noWhitespaceKeys(file); err != nil { return err }

Try / catch

if _, err := kvfile.Parse(file, nil); err != nil {
    return err // invalid env file (<file>): variable '<key>' contains whitespaces
}

Prevention

Never put a space before '=' ('VAR=value', not 'VAR =value').
Use underscores, not spaces, in variable names.
Enable 'show whitespace' in your editor for env files.

When it happens

Trigger: An --env-file line 'MY VAR=value' (space inside name), 'VAR =value' (trailing space before '='), or a tab in the variable name.

Common situations: Editors with visible-whitespace off leaving a stray space before '=', descriptive names with spaces, or copy-paste from documentation that included formatting spaces.

Related errors

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

Appendix: source

Thrown at pkg/kvfile/kvfile.go:112

		// trim the line from all leading whitespace first. trailing whitespace
		// is part of the value, and is kept unmodified.
		line := strings.TrimLeftFunc(string(scannedBytes), unicode.IsSpace)

		if len(line) == 0 || line[0] == '#' {
			// skip empty lines and comments (lines starting with '#')
			continue
		}

		key, _, hasValue := strings.Cut(line, "=")
		if len(key) == 0 {
			return []string{}, fmt.Errorf("no variable name on line '%s'", line)
		}

		// leading whitespace was already removed from the line, but
		// variables are not allowed to contain whitespace or have
		// trailing whitespace.
		if strings.ContainsAny(key, whiteSpaces) {
			return []string{}, fmt.Errorf("variable '%s' contains whitespaces", key)
		}

		if hasValue {
			// key/value pair is valid and has a value; add the line as-is.
			lines = append(lines, line)
			continue
		}

		if lookupFn != nil {
			// No value given; try to look up the value. The value may be
			// empty but if no value is found, the key is omitted.
			if value, found := lookupFn(line); found {
				lines = append(lines, key+"="+value)
			}
		}
	}
	return lines, scanner.Err()
}

View on GitHub (pinned to 4f84911bfe)