What causes "invalid environment variable: {val}" in docker/cli?

Ensure the environment variable string starts with a non-empty key before any '=' sign.

invalid environment variable: {val}

Error message

invalid environment variable: {val}

What it means

Returned by ValidateEnv (opts/env.go:21) when the environment variable string has an empty key — the part before '=' is empty. Per the code comments (moby-25099), only the emptiness of the key is checked; the key name itself is not otherwise validated, as that is deferred to the container application (moby-16585). If no '=' is present and the key is non-empty, the value is looked up from the host environment.

Source

Thrown at opts/env.go:21

import (
	"errors"
	"os"
	"strings"
)

// ValidateEnv validates an environment variable and returns it.
// If no value is specified, it obtains its value from the current environment.
//
// Environment variable names are not validated, and it's up to the application
// inside the container to validate them (see [moby-16585]). The only validation
// here is to check if name is empty, per [moby-25099].
//
// [moby-16585]: https://github.com/moby/moby/issues/16585
// [moby-25099]: https://github.com/moby/moby/issues/25099
func ValidateEnv(val string) (string, error) {
	k, _, hasValue := strings.Cut(val, "=")
	if k == "" {
		return "", errors.New("invalid environment variable: " + val)
	}
	if hasValue {
		// val contains a "=" (but value may be an empty string)
		return val, nil
	}
	if envVal, ok := os.LookupEnv(k); ok {
		return k + "=" + envVal, nil
	}
	return val, nil
}

View on GitHub (pinned to 4f84911bfe)

Solutions

Ensure the environment variable string starts with a non-empty key before any '=' sign.
If passing KEY without a value (to inherit from host env), ensure the key name is present and non-empty.
Check for stray '=' at the start of -e arguments.

Example fix

// before: empty key
// docker run -e =PATH nginx

// after: valid key
// docker run -e PATH nginx
// or with explicit value:
// docker run -e PATH=/usr/bin nginx

Defensive patterns

Strategy: validation

Validate before calling

func validateEnvKey(val string) error {
    k, _, _ := strings.Cut(val, "=")
    if k == "" {
        return fmt.Errorf("environment variable must have a non-empty key: %q", val)
    }
    return nil
}

Try / catch

if _, err := opts.ValidateEnv(val); err != nil {
    if strings.Contains(err.Error(), "invalid environment variable") {
        return fmt.Errorf("bad env var %q: key before '=' must not be empty", val)
    }
    return err
}

Prevention

Ensure environment variable strings have a non-empty key before any '='.
Check for stray leading '=' characters in -e flag values.
Validate env var lists from configuration files before passing to ValidateEnv.

When it happens

Trigger: ValidateEnv is called with a string where strings.Cut on '=' yields an empty key — e.g., '=value' (key before = is empty), or an empty string ''. ValidateEnv("=FOO") or ValidateEnv("") both trigger this.

Common situations: Malformed -e flag with a leading '=' (e.g., -e =PATH), empty environment variable string from shell expansion of an unset variable, or a programmatic error building the env list.

Related errors

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