valyala/fasthttp · error · ErrSmallBuffer

error when reading response headers: %w

Error message

error when reading response headers: %w

What it means

ReadHeader (response) failed while reading bytes from the connection reader. If the underlying error is a small-buffer/small-read condition, fasthttp wraps ErrSmallReadBuffer into an ErrSmallBuffer explaining that response headers could not be read within the buffer limits.

Source

Thrown at header.go:2206

	if len(b) == 0 {
		// Return ErrTimeout on any timeout.
		if x, ok := err.(interface{ Timeout() bool }); ok && x.Timeout() {
			return ErrTimeout
		}
		// treat all other errors on the first byte read as EOF
		if n == 1 || err == io.EOF {
			return io.EOF
		}

		// This is for go 1.6 bug. See https://github.com/golang/go/issues/14121 .
		if err == bufio.ErrBufferFull {
			if h.secureErrorLogMessage {
				return &ErrSmallBuffer{
					error: ErrReadingResponseHeaders,
				}
			}
			return &ErrSmallBuffer{
				error: fmt.Errorf("error when reading response headers: %w", ErrSmallReadBuffer),
			}
		}

		return fmt.Errorf("error when reading response headers: %w", err)
	}
	b = mustPeekBuffered(r)
	headersLen, errParse := h.parse(b)
	if errParse != nil {
		return headerError("response", err, errParse, b, h.secureErrorLogMessage)
	}
	mustDiscard(r, headersLen)
	return nil
}

// ReadTrailer reads response trailer header from r.
//
// io.EOF is returned if r is closed before reading the first byte.
func (h *header) ReadTrailer(r *bufio.Reader) error {

View on GitHub (pinned to c96f600972)

Solutions

1. Increase Client.ReadBufferSize (e.g. to 64KB+)
2. Reduce the size of response headers sent by the backend
3. If using ErrSmallBuffer handling, treat it as a buffer-size problem, not a network failure
4. Check intermediate proxies that may inject headers

Example fix

// before
client := &fasthttp.Client{ReadBufferSize: 4096}
// after
client := &fasthttp.Client{ReadBufferSize: 65536}

// estimate header size; set client.ReadBufferSize >= max expected headers

func isErrSmallBuffer(err error) bool { var e *fasthttp.ErrSmallBuffer; return errors.As(err, &e) }

if err := client.Do(req, resp); err != nil { if isErrSmallBuffer(err) { client.ReadBufferSize *= 4; retry() } }

When it happens

Trigger: ClientResponse / HostClient reading a server response when the header buffer is too small: response headers exceed the buffer size and ReadBufferSize is too small, or a partial read occurred.

Common situations: Server sending unusually large response headers (huge Set-Cookie lists) while Client.ReadBufferSize is small; proxies adding headers; misconfigured client buffers.

Related errors

• error when reading response trailer: %w
• error when reading %s headers: %w: buffer size=%d
• fasthttp: pipelined requests' queue has been overflowed. inc
• proxy: unknown scheme:
• dont support the network:

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