docker/cli · error · errdefs.ErrInvalidParameter

failed to parse custom headers from %s environment variable:

Error message

failed to parse custom headers from %s environment variable: value must be formatted as comma-separated key=value pairs

What it means

Error "failed to parse custom headers from %s environment variable: value must be formatted as comma-separated key=value pairs" thrown in docker/cli.

Source

Thrown at cli/command/cli_options.go:179

// environment variable is the equivalent to the HttpHeaders field in the
// configuration file.
//
// WARNING: If both config and environment-variable are set, the environment-
// variable currently overrides all headers set in the configuration file.
// This behavior may change in a future update, as we are considering the
// environment-variable to be appending to existing headers (and to only
// override headers with the same name).
//
// TODO(thaJeztah): this is a client Option, and should be moved to the client. It is non-exported for that reason.
func withCustomHeadersFromEnv() (client.Opt, error) {
	value := os.Getenv(envOverrideHTTPHeaders)
	if value == "" {
		return nil, nil
	}
	csvReader := csv.NewReader(strings.NewReader(value))
	fields, err := csvReader.Read()
	if err != nil {
		return nil, invalidParameter(fmt.Errorf(
			"failed to parse custom headers from %s environment variable: value must be formatted as comma-separated key=value pairs",
			envOverrideHTTPHeaders,
		))
	}
	if len(fields) == 0 {
		return nil, nil
	}

	env := map[string]string{}
	for _, kv := range fields {
		k, v, hasValue := strings.Cut(kv, "=")

		// Only strip whitespace in keys; preserve whitespace in values.
		k = strings.TrimSpace(k)

		if k == "" {
			return nil, invalidParameter(fmt.Errorf(
				`failed to set custom headers from %s environment variable: value contains a key=value pair with an empty key: '%s'`,

View on GitHub (pinned to e9452d6e78)

When it happens

Trigger: Thrown at cli/command/cli_options.go:179 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/5507b510ad014fb0.json. Report an issue: GitHub.