{"record":{"id":"15a1007aa33989d1","repo":"docker/cli","slug":"failed-to-set-custom-headers-from-s-environment-v","errorCode":null,"errorMessage":"failed to set custom headers from %s environment variable: value contains a key=value pair with an empty key: '%s'","messagePattern":"failed to set custom headers from (.+?) environment variable: value contains a key=value pair with an empty key: '(.+?)'","errorType":"validation","errorClass":"invalidParameterErr","httpStatus":null,"severity":"error","filePath":"cli/command/cli_options.go","lineNumber":196,"sourceCode":"\tif err != nil {\n\t\treturn nil, invalidParameter(fmt.Errorf(\n\t\t\t\"failed to parse custom headers from %s environment variable: value must be formatted as comma-separated key=value pairs\",\n\t\t\tenvOverrideHTTPHeaders,\n\t\t))\n\t}\n\tif len(fields) == 0 {\n\t\treturn nil, nil\n\t}\n\n\tenv := map[string]string{}\n\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}","sourceCodeStart":178,"sourceCodeEnd":214,"githubUrl":"https://github.com/docker/cli/blob/4f84911bfe8811e9b028e4b1fee8e7510be79387/cli/command/cli_options.go#L178-L214","documentation":"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.","triggerScenarios":"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.","commonSituations":"Trailing comma producing an empty trailing field ('X-Foo=val,'), a typo like '=val', or whitespace-only fields from copy-paste artifacts.","solutions":["Remove fields with empty keys; ensure every pair has a non-empty header name before '='.","Trim stray commas and whitespace from the value before exporting.","Validate each comma-separated token contains a non-empty name on the left of '='."],"exampleFix":"// before\nexport DOCKER_CUSTOM_HEADERS='X-Foo=val,=extra'   # second pair has empty key\n// after\nexport DOCKER_CUSTOM_HEADERS='X-Foo=val,X-Extra=extra'","handlingStrategy":"validation","validationCode":"// Validate every field has a non-empty key after trimming.\nfunc validateHeaderFields(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        k, _, _ := strings.Cut(kv, \"=\")\n        if strings.TrimSpace(k) == \"\" {\n            return fmt.Errorf(\"empty header key in pair %q\", kv)\n        }\n    }\n    return nil\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Strip trailing commas and stray whitespace before exporting.","Mentally pair each comma-separated token to a non-empty header name."],"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"}