valyala/fasthttp · error

forbidden trailer key %q

Error message

forbidden trailer key %q

What it means

Chunked-transfer trailer keys are validated against RFC 7230 §4.1.2: only header fields explicitly permitted for trailers may appear. fasthttp throws this when a trailer key is in the forbidden set (e.g. Transfer-Encoding, Content-Length, Host, Trailer itself).

Source

Thrown at header.go:2747

}

func parseTrailer(src []byte, dest []argsKV, disableNormalizing bool) ([]argsKV, int, error) {
	var s headerScanner
	s.b = src

	for s.next() {
		// Trim trailing whitespace before the colon to normalize headers
		// like "Content-Length :" to "Content-Length:".
		s.key = trimTrailingSpace(s.key)

		if len(s.key) == 0 {
			continue
		}
		// Key bytes were already validated by the scanner.
		disable := disableNormalizing || s.keyHasSpace
		// Forbidden by RFC 7230, section 4.1.2
		if isBadTrailer(s.key) {
			return dest, 0, fmt.Errorf("forbidden trailer key %q", s.key)
		}
		for _, ch := range s.value {
			if !validHeaderValueByte(ch) {
				return dest, 0, fmt.Errorf("invalid trailer value %q", s.value)
			}
		}
		normalizeHeaderKeyValidated(s.key, disable)
		dest = appendArgBytes(dest, s.key, s.value, argsHasValue)
	}
	if s.err != nil {
		return dest, 0, s.err
	}
	return dest, s.r, nil
}

func isBadTrailer(key []byte) bool {
	if len(key) == 0 {
		return true

View on GitHub (pinned to c96f600972)

Solutions

1. Fix the sender to omit forbidden headers from the trailer section (send them before the body instead)
2. Reject the request at an upstream proxy that sanitizes trailers
3. If you control the client library, upgrade it — older stacks may emit non-compliant trailers

var forbiddenTrailers = map[string]bool{
    "transfer-encoding": true, "content-length": true, "host": true,
    "trailer": true, "te": true, "connection": true,
}
// validate before sending trailers from your own client
func trailerKeyAllowed(k string) bool { return !forbiddenTrailers[strings.ToLower(k)] }

if err := h.Read(br); err != nil && strings.Contains(err.Error(), "forbidden trailer key") {
    http.Error(w, "bad trailer", fasthttp.StatusBadRequest)
    return
}

When it happens

Trigger: Reading a request or response with chunked transfer encoding whose trailer section contains a key matched by isBadTrailer — during header trailer parsing (readTrailer).

Common situations: Misbehaving HTTP clients or proxies emitting forbidden end-of-body trailer fields; hand-rolled HTTP senders appending hop-by-hop headers as trailers; fuzzers.

Understand the failure class

• Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

• fasthttp: contain forbidden trailer
• fasthttp: error when reading response trailer
• invalid trailer value %q
• fasthttp: error when reading response headers
• fasthttp: cannot find whitespace in the first line of respon

AI-assisted analysis of valyala/fasthttp@c96f600972 (2026-08-31). Data as JSON: /api/errors/5c2e6c8278801356. Report an issue: GitHub.