{"record":{"id":"979aa8a03627bf52","repo":"caddyserver/caddy","slug":"invalid-header-flag-v","errorCode":null,"errorMessage":"invalid header flag: %v","messagePattern":"invalid header flag: (.+?)","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"modules/caddyhttp/reverseproxy/command.go","lineNumber":187,"sourceCode":"\t\t} else {\n\t\t\t// expand a port range into multiple upstreams\n\t\t\tfor i := parsedAddr.StartPort; i <= parsedAddr.EndPort; i++ {\n\t\t\t\tupstreamPool = append(upstreamPool, &Upstream{\n\t\t\t\t\tDial: caddy.JoinNetworkAddress(\"\", parsedAddr.Host, fmt.Sprint(i)),\n\t\t\t\t})\n\t\t\t}\n\t\t}\n\t}\n\n\thandler := Handler{\n\t\tTransportRaw: caddyconfig.JSONModuleObject(ht, \"protocol\", \"http\", nil),\n\t\tUpstreams:    upstreamPool,\n\t}\n\n\t// set up header_up\n\theaderUp, err := fs.GetStringArray(\"header-up\")\n\tif err != nil {\n\t\treturn caddy.ExitCodeFailedStartup, fmt.Errorf(\"invalid header flag: %v\", err)\n\t}\n\tif len(headerUp) > 0 {\n\t\treqHdr := make(http.Header)\n\t\tfor i, h := range headerUp {\n\t\t\tkey, val, found := strings.Cut(h, \":\")\n\t\t\tkey, val = strings.TrimSpace(key), strings.TrimSpace(val)\n\t\t\tif !found || key == \"\" || val == \"\" {\n\t\t\t\treturn caddy.ExitCodeFailedStartup, fmt.Errorf(\"header-up %d: invalid format \\\"%s\\\" (expecting \\\"Field: value\\\")\", i, h)\n\t\t\t}\n\t\t\treqHdr.Set(key, val)\n\t\t}\n\t\thandler.Headers = &headers.Handler{\n\t\t\tRequest: &headers.HeaderOps{\n\t\t\t\tSet: reqHdr,\n\t\t\t},\n\t\t}\n\t}\n","sourceCodeStart":169,"sourceCodeEnd":205,"githubUrl":"https://github.com/caddyserver/caddy/blob/50e54ee279aa1e504fe218ca49ab6ae16c100410/modules/caddyhttp/reverseproxy/command.go#L169-L205","documentation":"Thrown by the `caddy reverse-proxy` CLI command when the `--header-up` flag value cannot be read as a string array by pflag. This is a flag-parsing failure, not a header-format failure: the command line argument itself was malformed for the flag library. Caddy aborts startup with ExitCodeFailedStartup.","triggerScenarios":"Running `caddy reverse-proxy --header-up ...` with a flag value pflag cannot interpret as a StringArray (e.g. the flag was already consumed as a different type, or a custom flag set misregistered the option). The source calls `fs.GetStringArray(\"header-up\")` and any error from it is wrapped here.","commonSituations":"Typos in the flag name, using `=` vs space forms inconsistently, scripting the command with unquoted shell expansions that collapse or drop values, or version drift between Caddy releases that changed flag registration.","solutions":["Check the exact spelling and casing of --header-up against `caddy reverse-proxy --help` output for your binary","Quote each header argument fully in shell scripts: --header-up \"Field: value\"","Verify you are not mixing --header-up with deprecated or renamed flags from an older Caddy version","Print the command as executed (e.g. `set -x` in bash) to see what the shell actually passed"],"exampleFix":"# before\ncaddy reverse-proxy --to localhost:9000 --header-up Host:example.com X-Custom:1\n# after\ncaddy reverse-proxy --to localhost:9000 --header-up \"Host: example.com\" --header-up \"X-Custom: 1\"","handlingStrategy":"validation","validationCode":"# before invoking, assert the flag parses as a repeated string array\nif ! grep -qE -- '--header-up[= ]+[^ ].*' <<< \"$*\"; then echo \"bad --header-up\"; exit 1; fi\n# simplest: always pass quoted \"Field: value\" pairs and check exit code of caddy","typeGuard":null,"tryCatchPattern":"cmd := exec.Command(\"caddy\", \"reverse-proxy\", \"--to\", to)\nif out, err := cmd.CombinedOutput(); err != nil {\n\tlog.Printf(\"reverse-proxy failed: %v\\n%s\", err, out)\n\tos.Exit(1)\n}","preventionTips":["Quote every header flag value in shell scripts","Pin the Caddy version in deployment scripts so flag surface does not drift","Prefer a Caddyfile over ad-hoc CLI flags for anything non-trivial"],"tags":["cli","reverse-proxy","headers","startup"],"backgroundTag":null,"analyzedSha":"50e54ee279aa1e504fe218ca49ab6ae16c100410","analyzedAt":"2026-08-15T09:20:21.641Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}