valyala/fasthttp · error

fasthttp: small read buffer. increase readbuffersize

Error message

fasthttp: small read buffer. increase readbuffersize

What it means

fasthttp returns ErrSmallReadBuffer when a single header line (or request line) is longer than the configured read buffer size, so the header parser cannot fit the line into the buffer. The library does not grow the buffer automatically; instead it tells you to increase ReadBufferSize. It is thrown by header parsing in header.go when the parser runs out of buffer space mid-line.

Source

Thrown at header.go:482

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

View on GitHub (pinned to c96f600972)

Solutions

1. Increase ReadBufferSize on fasthttp.Server (and/or fasthttp.HostClient/Client) to exceed the longest expected header line, e.g. 16384 or 65536.
2. Reduce incoming header size upstream (strip/limit cookies, split large headers, use a proxy that trims headers).
3. If you control the client, move large payloads from headers into the request body.
4. As a last resort raise Server.MaxRequestBodySize-adjacent tuning only after confirming the offending header length via logs.

Example fix

// before
server := &fasthttp.Server{Handler: h}
// after
server := &fasthttp.Server{Handler: h, ReadBufferSize: 16384}

const maxHeaderLine = 4096
func fitsReadBuffer(headerLine []byte, bufSize int) bool {
    return len(headerLine) < bufSize
}
// before sending/receiving, ensure bufSize (Server/Client ReadBufferSize) > longest header line

if err := fasthttp.Do(req, resp); err != nil {
    if errors.Is(err, fasthttp.ErrSmallReadBuffer) {
        // bump client.ReadBufferSize and retry once
    }
}

When it happens

Trigger: Parsing an HTTP request/response whose header line (e.g. a very long Cookie, Authorization, or URL) exceeds Server.ReadBufferSize or Client.ReadBufferSize (default 4096 bytes). Happens during ServeConn/workerFunc or client response header reading.

Common situations: Servers receiving requests with huge cookies or OAuth/JWT bearer tokens in headers; proxies forwarding many X-Forwarded-* headers; clients talking to servers that emit very large Set-Cookie or headers; teams leaving ReadBufferSize at the default.

Related errors

• fasthttp: duplicate content-length header
• fasthttp: unsupported transfer-encoding
• fasthttp: non-numeric chars found
• error when reading %s headers: %w: buffer size=%d, contents:
• error when reading request headers: %w (n=%d, reader buffere

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