valyala/fasthttp · error

fasthttp: contain forbidden trailer

Error message

fasthttp: contain forbidden trailer

What it means

ErrBadTrailer is returned by header.AddTrailer when the supplied trailer name is in the forbidden set (e.g. hop-by-hop or pseudo headers like Content-Length, Transfer-Encoding, Host) and may not be sent as an HTTP trailer. The library validates trailer names to keep the response well-formed per RFC 7230.

Source

Thrown at header.go:469

//
// Trailers are only supported with chunked transfer.
// Trailers allow the sender to include additional headers at the end of chunked messages.
//
// The following trailers are forbidden:
// 1. necessary for message framing (e.g., Transfer-Encoding and Content-Length),
// 2. routing (e.g., Host),
// 3. request modifiers (e.g., controls and conditionals in Section 5 of [RFC7231]),
// 4. authentication (e.g., see [RFC7235] and [RFC6265]),
// 5. response control data (e.g., see Section 7.1 of [RFC7231]),
// 6. determining how to process the payload (e.g., Content-Encoding, Content-Type, Content-Range, and Trailer)
//
// Return ErrBadTrailer if contain any forbidden trailers.
func (h *header) AddTrailer(trailer string) error {
	return h.AddTrailerBytes(s2b(trailer))
}

var (
	ErrBadTrailer                    = errors.New("fasthttp: contain forbidden trailer")
	ErrReadingResponseHeaders        = errors.New("fasthttp: error when reading response headers")
	ErrReadingResponseTrailer        = errors.New("fasthttp: error when reading response trailer")
	ErrResponseFirstLineMissingSpace = errors.New("fasthttp: cannot find whitespace in the first line of response")
	ErrUnexpectedStatusCodeChar      = errors.New("fasthttp: unexpected char at the end of status code")
	ErrMissingRequestMethod          = errors.New("fasthttp: cannot find http request method")
	ErrUnsupportedRequestMethod      = errors.New("fasthttp: unsupported http request method")
	ErrExtraWhitespaceInRequestLine  = errors.New("fasthttp: extra whitespace in request line")
	ErrEmptyRequestURI               = errors.New("fasthttp: requesturi cannot be empty")
	ErrDuplicateContentLength        = errors.New("fasthttp: duplicate content-length header")
	ErrUnsupportedTransferEncoding   = errors.New("fasthttp: unsupported transfer-encoding")
	ErrNonNumericChars               = errors.New("fasthttp: non-numeric chars found")
	ErrNeedMore                      = errors.New("fasthttp: need more data: cannot find trailing lf")
	ErrSmallReadBuffer               = errors.New("fasthttp: small read buffer. increase readbuffersize")
)

// AddTrailerBytes add Trailer header value for chunked response
// to indicate which headers will be sent after the body.
//

View on GitHub (pinned to c96f600972)

Solutions

  1. Remove the forbidden trailer from the list before calling AddTrailer
  2. Filter headers with an allowlist (e.g. only custom X- headers) when proxying trailers
  3. Send the value as a normal response header instead of a trailer
  4. Normalize header names (trim spaces, canonical case) before validation

Example fix

// before
resp.Header.AddTrailer("Content-Length") // forbidden
// after
resp.Header.AddTrailer("X-Checksum-CRC32") // allowed trailer
Defensive patterns

Strategy: validation

Validate before calling

var forbidden = map[string]bool{"content-length": true, "transfer-encoding": true, "host": true}
if forbidden[strings.ToLower(strings.TrimSpace(name))] {
    return fmt.Errorf("trailer %q is forbidden", name)
}

Try / catch

if err := resp.Header.AddTrailer(name); err != nil {
    if errors.Is(err, fasthttp.ErrBadTrailer) {
        // send as a normal header instead
        resp.Header.Set(name, value)
    }
}

Prevention

When it happens

Trigger: Calling Response.Header.AddTrailer(name) or AddTrailerBytes with a forbidden header name; also surfaced by TestExportedErrorStrings when validating exported error messages.

Common situations: Copying all upstream response headers into trailers when proxying; hand-building chunked responses and accidentally including Content-Length/Transfer-Encoding/Host as trailers.

Understand the failure class

Related errors

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