docker/cli · error

invalid label ' ': empty name

Error message

invalid label '%s': empty name

What it means

Thrown by ValidateLabel (opts.go:243) when, after splitting on '=' and trimming leading whitespace, the key is empty. Docker labels are key=value pairs; the key (label name) is mandatory. A value may be omitted (defaults to empty), but a key with no name — e.g. `=value`, ` =value`, or just `=` — is rejected.

Solutions

1. Provide a non-empty key before the '=', e.g. `--label com.example.team=payments`.
2. If constructing labels programmatically, check the key is non-empty before joining with '='.
3. For a label with no value, use `--label com.example.flag` (the value is optional) rather than `--label =x`.
4. Audit env-var substitution so empty variables don't become empty keys.

Example fix

// before
--label =$LABEL_VALUE
// after
--label com.example.role=$LABEL_VALUE

// Verify the label has a non-empty key before joining/validating.
func validLabel(s string) error {
    key, _, _ := strings.Cut(s, "=")
    if strings.TrimLeft(key, " \t") == "" {
        return fmt.Errorf("label key is empty in %q", s)
    }
    return nil
}

if err := validLabel(l); err != nil { return err }

When it happens

Trigger: Calling ValidateLabel with `=foo`, ` =foo`, `=`, or a string whose only content before '=' is whitespace. strings.Cut at line 240 yields an empty key, TrimLeft at 241 leaves it empty, and the check at 242 fires.

Common situations: Shell-expanding an empty variable as the key (`--label =$VAR`), malformed config from a YAML/JSON file where the key was null, copy-paste dropping the key, or building label strings by concatenation with a missing left operand.

Related errors

• label ' ' contains whitespaces
• is not a valid domain
• sysctl ' ' is not allowed
• failed to parse as a rational number
• invalid size

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

Appendix: source

Thrown at opts/opts.go:243

const whiteSpaces = " \t"

// 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,

View on GitHub (pinned to 4f84911bfe)