docker/cli · error

invalid environment variable: %s

Error message

invalid environment variable: %s

What it means

Error "invalid environment variable: %s" thrown in docker/cli.

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 e9452d6e78)

When it happens

Trigger: Thrown at opts/env.go:21 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of docker/cli@e9452d6e78 (2026-08-01). Data as JSON: /data/errors/70400ebbb66d5fea.json. Report an issue: GitHub.