valyala/fasthttp · error

fasthttp: unsupported transfer-encoding

Error message

fasthttp: unsupported transfer-encoding

What it means

fasthttp supports only specific Transfer-Encoding values (chiefly 'chunked' or identity/none). When a parsed message carries an unsupported Transfer-Encoding header value, ErrUnsupportedTransferEncoding is returned. This prevents ambiguous body framing that could break streaming or enable smuggling.

Source

Thrown at header.go:479

// 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.
//
// 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]),

View on GitHub (pinned to c96f600972)

Solutions

1. Make the sender use 'Transfer-Encoding: chunked' for streaming bodies or plain Content-Length framing otherwise.
2. If the intent was compression, move it to 'Content-Encoding: gzip' and keep Transfer-Encoding as chunked.
3. Remove the header entirely when body framing is Content-Length based: h.Del("Transfer-Encoding").
4. Update the intermediate proxy/middleware that emits the unsupported value.

Example fix

// before
w.Header("Transfer-Encoding", "gzip") // unsupported coding
// after
w.Header("Content-Encoding", "gzip")
// (body still chunked or Content-Length framed)

te := string(req.Header.Peek("Transfer-Encoding"))
t := strings.ToLower(strings.TrimSpace(te))
if t != "" && t != "chunked" {
    return fmt.Errorf("unsupported transfer-encoding %q", te)
}

func isUnsupportedTransferEncoding(err error) bool {
    return err == fasthttp.ErrUnsupportedTransferEncoding
}

if err := client.Do(req, resp); err == fasthttp.ErrUnsupportedTransferEncoding {
    return fmt.Errorf("peer uses unsupported transfer-encoding: %w", err)
}

When it happens

Trigger: Request/Response Read on headers like 'Transfer-Encoding: gzip, chunked' (multi-coding) or 'Transfer-Encoding: deflate'; setting h.SetTransferEncoding to a non-chunked value; proxies that convert content-encoding into transfer-encoding incorrectly.

Common situations: Upstream gateways emitting 'Transfer-Encoding: gzip' instead of Content-Encoding: gzip; custom clients sending exotic transfer codings; compression middleware misconfigured on the sending side.

Related errors

• fasthttp: duplicate content-length header
• fasthttp: non-numeric chars found
• fasthttp: small read buffer. increase readbuffersize
• error when reading %s headers: %w: buffer size=%d, contents:
• unsupported transfer-encoding: %q

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