docker/cli · error

label ' ' contains whitespaces

Error message

label '%s' contains whitespaces

What it means

Thrown by ValidateLabel (opts.go:246) when the label key (after left-trimming whitespace) still contains a space or tab. Docker label keys must not contain whitespace so they can be parsed and indexed unambiguously. Only leading whitespace is stripped; internal/embedded whitespace in the key is invalid.

Solutions

1. Remove all spaces and tabs from the label key; use dots, hyphens, or underscores as separators.
2. Quote the argument so the shell treats it as one token: `--label "com.example.foo=1"`.
3. If the space was meant to separate multiple labels, pass `--label` multiple times instead.
4. Run the key through a pre-check: `if strings.ContainsAny(key, " \t") { ... }`.

Example fix

// before
--label com example team=payments
// after
--label com.example.team=payments

// Reject label keys containing whitespace before submission.
key, _, _ := strings.Cut(label, "=")
if strings.ContainsAny(strings.TrimLeft(key, " \t"), " \t") {
    return fmt.Errorf("label key %q contains whitespace", key)
}

When it happens

Trigger: Calling ValidateLabel with a key containing a space or tab, e.g. `my label=value`, `a b=x`, or `com example.foo=1`. After TrimLeft the first whitespace is gone but internal spaces remain, so ContainsAny against ` \t` at line 245 returns true.

Common situations: Unquoted CLI arguments split by the shell (`--label com example.foo=1`), keys copied from a table/spreadsheet with spaces, tab characters from copy-paste, or a missing '=' making a multi-word phrase parse as the key.

Related errors

• invalid label ' ': empty name
• invalid value for ' ' in ' ': value should not have…
• is not a valid domain
• sysctl ' ' is not allowed
• failed to parse as a rational number

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

Appendix: source

Thrown at opts/opts.go:246

// ValidateLabel validates that the specified string is a valid label, and returns it.
//
// Labels are in the form of key=value; key must be a non-empty string, and not
// contain whitespaces. A value is optional (defaults to an empty string if omitted).
//
// Leading whitespace is removed during validation but values are kept as-is
// otherwise, so any string value is accepted for both, which includes whitespace
// (for values) and quotes (surrounding, or embedded in key or value).
//
// TODO discuss if quotes (and other special characters) should be valid or invalid for keys
// TODO discuss if leading/trailing whitespace in keys should be preserved (and valid)
func ValidateLabel(value string) (string, error) {
	key, _, _ := strings.Cut(value, "=")
	key = strings.TrimLeft(key, whiteSpaces)
	if key == "" {
		return "", fmt.Errorf("invalid label '%s': empty name", value)
	}
	if strings.ContainsAny(key, whiteSpaces) {
		return "", fmt.Errorf("label '%s' contains whitespaces", key)
	}
	return value, nil
}

// ValidateSysctl validates a sysctl and returns it.
func ValidateSysctl(val string) (string, error) {
	validSysctlMap := map[string]bool{
		"kernel.msgmax":          true,
		"kernel.msgmnb":          true,
		"kernel.msgmni":          true,
		"kernel.sem":             true,
		"kernel.shmall":          true,
		"kernel.shmmax":          true,
		"kernel.shmmni":          true,
		"kernel.shm_rmid_forced": true,
	}
	validSysctlPrefixes := []string{
		"net.",

View on GitHub (pinned to 4f84911bfe)