What causes "header %s not found" in crowdsecurity/crowdsec?

Add the required header with the API key to the request.

header %s not found

Error message

header %s not found

What it means

For header-located apiKey security schemes, the validator looks up the scheme's header name (canonically keyed) in the request headers. If the header is absent, this error is returned because the required API key is missing.

Source

Thrown at pkg/appsec/api_validation/api_validation.go:264

				authTokenValue = values[0][7:]
			}
		case "apiKey":
			switch input.SecurityScheme.In {
			case "query":
				//Because we are checking for the presence of the API key, it probably does not matter if go drops parameters using ; as a separator
				values := input.RequestValidationInput.Request.URL.Query()[input.SecurityScheme.Name]
				if len(values) == 0 {
					return fmt.Errorf("query parameter %s not found", input.SecurityScheme.Name)
				}
				if len(values) > 1 {
					return fmt.Errorf("multiple query parameters with name %s found", input.SecurityScheme.Name)
				}
				authTokenValue = values[0]
			case "header":
				canonicalHeaderName := http.CanonicalHeaderKey(input.SecurityScheme.Name)
				values := input.RequestValidationInput.Request.Header[canonicalHeaderName]
				if len(values) == 0 {
					return fmt.Errorf("header %s not found", input.SecurityScheme.Name)
				}
				if len(values) > 1 {
					return fmt.Errorf("multiple headers with name %s found", input.SecurityScheme.Name)
				}
				authTokenValue = values[0]
			case "cookie":
				cookieValues := input.RequestValidationInput.Request.CookiesNamed(input.SecurityScheme.Name)
				if len(cookieValues) == 0 {
					return fmt.Errorf("cookie %s not found", input.SecurityScheme.Name)
				}
				if len(cookieValues) > 1 {
					return fmt.Errorf("multiple cookies with name %s found", input.SecurityScheme.Name)
				}
				authTokenValue = cookieValues[0].Value
			default:
				return fmt.Errorf("unsupported apiKey location %s", input.SecurityScheme.In)
			}
		case "oauth2", "openIdConnect":

View on GitHub (pinned to 909b515798)

Solutions

Add the required header with the API key to the request.
Verify the securityScheme Name in the spec matches the header name the client sends (canonical casing).
Check intermediate proxies/middleware for header stripping.

Example fix

// before
req, _ := http.NewRequest("GET", url, nil)
// after
req, _ := http.NewRequest("GET", url, nil)
req.Header.Set("X-API-Key", apiKey)

Defensive patterns

Strategy: validation

Validate before calling

if req.Header.Get("X-API-Key") == "" { return errors.New("X-API-Key header required") }

Try / catch

err := validator.ValidateRequest(input); if err != nil { if strings.Contains(err.Error(), "header") && strings.Contains(err.Error(), "not found") { return ErrMissingAPIKeyHeader } return err }

Prevention

Set auth headers in a shared client wrapper so they're never forgotten
Use http.CanonicalHeaderKey for lookups
Verify proxies don't strip custom headers

When it happens

Trigger: A request validated against a securityScheme with In: "header" lacks the named header — len(values) == 0 at pkg/appsec/api_validation/api_validation.go:264.

Common situations: Client forgets the Authorization/X-API-Key header; spec header name differs from what the client sends; middleware strips the header.

Understand the failure class

Background: "API key is required" / "API key not found" / "No API key was set": the missing-api-key error family across 16 libraries — this error's family across 16 libraries.

Related errors

AI-assisted analysis of crowdsecurity/crowdsec@909b515798 (2026-09-06). Data as JSON: /api/errors/f91da479e9c815fe. Report an issue: GitHub.