docker/cli · error · errdefs.ErrInvalidParameter

failed to set custom headers from %s environment variable: v

Error message

failed to set custom headers from %s environment variable: value contains a key=value pair with an empty key: '%s'

What it means

Error "failed to set custom headers from %s environment variable: value contains a key=value pair with an empty key: '%s'" thrown in docker/cli.

Source

Thrown at cli/command/cli_options.go:196

	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'`,
				envOverrideHTTPHeaders, kv,
			))
		}

		// We don't currently allow empty key=value pairs, and produce an error.
		// This is something we could allow in future (e.g. to read value
		// from an environment variable with the same name). In the meantime,
		// produce an error to prevent users from depending on this.
		if !hasValue {
			return nil, invalidParameter(fmt.Errorf(
				`failed to set custom headers from %s environment variable: missing "=" in key=value pair: '%s'`,
				envOverrideHTTPHeaders, kv,
			))
		}

		env[http.CanonicalHeaderKey(k)] = v
	}

View on GitHub (pinned to e9452d6e78)

When it happens

Trigger: Thrown at cli/command/cli_options.go:196 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/15a1007aa33989d1.json. Report an issue: GitHub.