hashicorp/nomad · error

Headers must be in the form 'Key: Value' but found: %q

Error message

Headers must be in the form 'Key: Value' but found: %q

What it means

This error is returned by headerFlags.Set, the pflag parser hook for the -http-addr-style repeatable header flag on operator commands. The flag expects each occurrence to be an HTTP header literal of the form 'Key: Value' with a colon separating key and value; the value is split on the first colon via strings.SplitN(v, ":", 2). If no colon is present the input cannot be interpreted as a header and this error aborts flag parsing.

Source

Thrown at command/operator_api.go:487

}

// headerFlags is a flag.Value implementation for collecting multiple -H flags.
type headerFlags struct {
	headers http.Header
}

func newHeaderFlags() *headerFlags {
	return &headerFlags{
		headers: make(http.Header),
	}
}

func (*headerFlags) String() string { return "" }

func (h *headerFlags) Set(v string) error {
	parts := strings.SplitN(v, ":", 2)
	if len(parts) != 2 {
		return fmt.Errorf("Headers must be in the form 'Key: Value' but found: %q", v)
	}

	h.headers.Add(parts[0], strings.TrimSpace(parts[1]))
	return nil
}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Rewrite the flag value to include a colon separating key and value: -header="Authorization: Bearer <token>"
2. Quote the whole argument so the shell does not split or mangle it: -header="X-Consul-Token: abc123"
3. Verify the env variable/secret you interpolate actually contains the 'Key: Value' form, not just the value
4. Each header needs its own -header flag occurrence; do not pack multiple headers into one value

Example fix

// before
consul operator debug -header=Authorization
// after
consul operator debug -header="Authorization: Bearer eyJhbGciOi..."

func validHeader(s string) bool {
	return strings.Contains(s, ":") && strings.SplitN(s, ":", 2)[0] != ""
}
if !validHeader(hdr) { return fmt.Errorf("header %q must be 'Key: Value'", hdr) }

When it happens

Trigger: Passing a header value without a colon to the repeatable header flag, e.g. `consul debug -header=Authorization` or `-header BearerToken`, instead of `-header=Authorization: Bearer xyz`. A typo'd flag such as `-headerfoo:bar` can also land here as the flag's Set value.

Common situations: Copy-pasting a bare token into the header flag; forgetting the space after the colon is fine but forgetting the colon entirely is not; scripting the command where an env var holding 'Key: Value' was empty or truncated to just the key; shell quoting stripping the colon.

Related errors

• Node ID must contain at least two characters.
• invalid digest format
• missing policy name
• not a terminal
• both -n and -c set

AI-assisted analysis of hashicorp/nomad@482b49bf1a (2026-09-04). Data as JSON: /api/errors/32dac37128435099. Report an issue: GitHub.