What causes "fasthttp: error when reading response trailer" in valyala/fasthttp?

Fix or update the server/proxy emitting the malformed chunked trailer

fasthttp: error when reading response trailer

Error message

fasthttp: error when reading response trailer

What it means

ErrReadingResponseTrailer indicates fasthttp failed while reading the trailer section that follows a chunked response body — malformed trailer lines or a truncated chunked stream. It is an exported sentinel from header.go.

Source

Thrown at header.go:471

// 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.
//
// Use Set to set the trailer header later.
//

View on GitHub (pinned to c96f600972)

Solutions

Fix or update the server/proxy emitting the malformed chunked trailer
Retry the request; if it's transient network truncation, use DoTimeout/DoRetry-style logic
If trailers are unnecessary, have the server omit the Trailer header and send plain chunked responses
Capture the raw bytes to confirm whether the peer or the client parser is at fault before filing a bug

Defensive patterns

Strategy: retry

Validate before calling

// prefer servers that either send valid trailers or omit the Trailer header
if strings.EqualFold(resp.Header.Peek("Transfer-Encoding") != nil && !trailerOK, true) { /* retry */ }

Try / catch

err := client.DoTimeout(req, resp, timeout)
if err != nil && errors.Is(err, fasthttp.ErrReadingResponseTrailer) {
    // transient truncation: retry with backoff
}

Prevention

Ensure upstream servers emit well-formed chunked trailers (name: value CRLF)
Avoid proxies known to truncate long chunked responses
Prefer non-chunked responses with Content-Length for large downloads
Set timeouts and bounded retries around streaming reads

When it happens

Trigger: Reading a chunked HTTP response that declares trailers but sends malformed trailer lines, closes the connection before the terminating CRLF, or violates chunk framing while trailers are expected.

Common situations: Unstable upstream servers/proxies dropping connections at end of chunked bodies; custom servers writing trailers with wrong syntax (missing colon/CRLF); network interruptions during large streamed downloads.

Related errors

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