{"record":{"id":"540b7c2b8cea6b30","repo":"docker/cli","slug":"failed-to-set-custom-headers-from-s-environment-v-540b7c","errorCode":null,"errorMessage":"failed to set custom headers from %s environment variable: missing \"=\" in key=value pair: '%s'","messagePattern":"failed to set custom headers from (.+?) environment variable: missing \"=\" in key=value pair: '(.+?)'","errorType":"validation","errorClass":"invalidParameterErr","httpStatus":null,"severity":"error","filePath":"cli/command/cli_options.go","lineNumber":207,"sourceCode":"\tfor _, kv := range fields {\n\t\tk, v, hasValue := strings.Cut(kv, \"=\")\n\n\t\t// Only strip whitespace in keys; preserve whitespace in values.\n\t\tk = strings.TrimSpace(k)\n\n\t\tif k == \"\" {\n\t\t\treturn nil, invalidParameter(fmt.Errorf(\n\t\t\t\t`failed to set custom headers from %s environment variable: value contains a key=value pair with an empty key: '%s'`,\n\t\t\t\tenvOverrideHTTPHeaders, kv,\n\t\t\t))\n\t\t}\n\n\t\t// We don't currently allow empty key=value pairs, and produce an error.\n\t\t// This is something we could allow in future (e.g. to read value\n\t\t// from an environment variable with the same name). In the meantime,\n\t\t// produce an error to prevent users from depending on this.\n\t\tif !hasValue {\n\t\t\treturn nil, invalidParameter(fmt.Errorf(\n\t\t\t\t`failed to set custom headers from %s environment variable: missing \"=\" in key=value pair: '%s'`,\n\t\t\t\tenvOverrideHTTPHeaders, kv,\n\t\t\t))\n\t\t}\n\n\t\tenv[http.CanonicalHeaderKey(k)] = v\n\t}\n\n\tif len(env) == 0 {\n\t\t// We should probably not hit this case, as we don't skip values\n\t\t// (only return errors), but we don't want to discard existing\n\t\t// headers with an empty set.\n\t\treturn nil, nil\n\t}\n\n\t// TODO(thaJeztah): add a client.WithExtraHTTPHeaders() function to allow these headers to be _added_ to existing ones, instead of _replacing_\n\t//  see https://github.com/docker/cli/pull/5098#issuecomment-2147403871  (when updating, also update the WARNING in the function and env-var GoDoc)\n\treturn client.WithHTTPHeaders(env), nil","sourceCodeStart":189,"sourceCodeEnd":225,"githubUrl":"https://github.com/docker/cli/blob/4f84911bfe8811e9b028e4b1fee8e7510be79387/cli/command/cli_options.go#L189-L225","documentation":"Returned by withCustomHeadersFromEnv() when a CSV field from DOCKER_CUSTOM_HEADERS contains no '=' at all (cli_options.go:206-211). strings.Cut(kv,\"=\") returns hasValue=false when the separator is absent, so a token like 'X-Custom-Header' (no '=value') is rejected as an invalidParameter. Every header token must be a key=value pair.","triggerScenarios":"Setting DOCKER_CUSTOM_HEADERS with a field that omits the '=' separator: 'X-Custom' instead of 'X-Custom=val', or a bare flag-like token. The per-field check fires as soon as any token lacks '='.","commonSituations":"Forgetting the value portion, using a header name as a toggle, or mixing key=value pairs with a bare header name.","solutions":["Ensure every comma-separated token is in key=value form, even if the value is empty use 'X-Header='.","Double-check for typos that dropped the '='.","Validate with: echo \"$DOCKER_CUSTOM_HEADERS\" | tr ',' '\\n' | grep -v '=' to spot offending tokens."],"exampleFix":"// before\nexport DOCKER_CUSTOM_HEADERS='X-Custom,Authorization=Bearer x'   # first token has no '='\n// after\nexport DOCKER_CUSTOM_HEADERS='X-Custom=value,Authorization=Bearer x'","handlingStrategy":"validation","validationCode":"// Ensure every field contains '='.\nfunc validateHeaderHasEquals(value string) error {\n    r := csv.NewReader(strings.NewReader(value))\n    fields, err := r.Read()\n    if err != nil { return err }\n    for _, kv := range fields {\n        if _, _, ok := strings.Cut(kv, \"=\"); !ok {\n            return fmt.Errorf(\"header token missing '=': %q\", kv)\n        }\n    }\n    return nil\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Every token must be name=value, even when the value is empty (use 'X-Empty=').","Spot-check with: echo \"$DOCKER_CUSTOM_HEADERS\" | tr ',' '\\n' | grep -v '='."],"tags":["environment-variable","http-headers","configuration","validation"],"backgroundTag":null,"analyzedSha":"4f84911bfe8811e9b028e4b1fee8e7510be79387","analyzedAt":"2026-08-07T12:15:29.814Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}