docker/cli · error · invalidParameterErr

failed to set custom headers from

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

Returned by withCustomHeadersFromEnv() when a CSV field from DOCKER_CUSTOM_HEADERS splits on '=' into a key that is empty after trimming whitespace (cli_options.go:190-200). strings.Cut(kv,"=") yields a key portion; if strings.TrimSpace(key) == "" the function rejects it as an invalidParameter. This catches tokens like '=value' or ' ,Next=val' where the left side is blank.

Solutions

1. Remove fields with empty keys; ensure every pair has a non-empty header name before '='.
2. Trim stray commas and whitespace from the value before exporting.
3. Validate each comma-separated token contains a non-empty name on the left of '='.

Example fix

// before
export DOCKER_CUSTOM_HEADERS='X-Foo=val,=extra'   # second pair has empty key
// after
export DOCKER_CUSTOM_HEADERS='X-Foo=val,X-Extra=extra'

// Validate every field has a non-empty key after trimming.
func validateHeaderFields(value string) error {
    r := csv.NewReader(strings.NewReader(value))
    fields, err := r.Read()
    if err != nil { return err }
    for _, kv := range fields {
        k, _, _ := strings.Cut(kv, "=")
        if strings.TrimSpace(k) == "" {
            return fmt.Errorf("empty header key in pair %q", kv)
        }
    }
    return nil
}

When it happens

Trigger: Setting DOCKER_CUSTOM_HEADERS with a field whose key is empty: a leading '=value', a field that is only whitespace, or a stray comma creating a blank field. The check fires per-field inside the loop, so any single offending pair aborts the whole set.

Common situations: Trailing comma producing an empty trailing field ('X-Foo=val,'), a typo like '=val', or whitespace-only fields from copy-paste artifacts.

Related errors

• failed to set custom headers from
• failed to parse custom headers from
• invalid environment variable
• DOCKER_BUILDKIT environment variable expects boolean value
• failed to read credentials from DOCKER_AUTH_CONFIG

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

Appendix: 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 4f84911bfe)