valyala/fasthttp · error

fasthttp: pipelined requests' queue has been overflowed. inc

Error message

fasthttp: pipelined requests' queue has been overflowed. increase maxconns and/or maxpendingrequests

What it means

ErrPipelineOverflow is returned by PipelineClient.Do/DoTimeout when the client's pending-requests queue is full because all pipeline connections already carry MaxPendingRequests queued requests. fasthttp enforces this bound so an unresponsive server cannot make the client buffer unbounded amounts of work. It is a backpressure signal, not a bug.

Source

Thrown at client.go:2993

		DialDualStack:                 c.DialDualStack,
		DisableHeaderNamesNormalizing: c.DisableHeaderNamesNormalizing,
		DisablePathNormalizing:        c.DisablePathNormalizing,
		IsTLS:                         c.IsTLS,
		TLSConfig:                     c.TLSConfig,
		MaxIdleConnDuration:           c.MaxIdleConnDuration,
		ReadBufferSize:                c.ReadBufferSize,
		WriteBufferSize:               c.WriteBufferSize,
		ReadTimeout:                   c.ReadTimeout,
		WriteTimeout:                  c.WriteTimeout,
		Logger:                        c.Logger,
	}
	c.connClients = append(c.connClients, cc)
	return cc
}

// ErrPipelineOverflow may be returned from PipelineClient.Do*
// if the requests' queue is overflowed.
var ErrPipelineOverflow = errors.New("fasthttp: pipelined requests' queue has been overflowed. " +
	"increase maxconns and/or maxpendingrequests")

// DefaultMaxPendingRequests is the default value
// for PipelineClient.MaxPendingRequests.
const DefaultMaxPendingRequests = 1024

func (c *pipelineConnClient) acquirePipelineConnChannels() *pipelineConnChannels {
	c.chLock.Lock()
	chs := c.chs
	if chs == nil {
		maxPendingRequests := c.MaxPendingRequests
		if maxPendingRequests <= 0 {
			maxPendingRequests = DefaultMaxPendingRequests
		}
		chs = &pipelineConnChannels{
			chR: make(chan *pipelineWork, maxPendingRequests),
			chW: make(chan *pipelineWork, maxPendingRequests),
		}

View on GitHub (pinned to c96f600972)

Solutions

1. Increase PipelineClient.MaxConns so requests spread over more pipeline connections
2. Increase PipelineClient.MaxPendingRequests to enlarge each connection's queue
3. Throttle callers (limit in-flight Do* calls) and retry on ErrPipelineOverflow with backoff
4. Investigate why the server responds slowly / out of order over the pipeline

Example fix

// before
client := &fasthttp.PipelineClient{}
for _, req := range reqs { client.Do(req, resp) }
// after
client := &fasthttp.PipelineClient{
    MaxConns:            16,
    MaxPendingRequests:  8192,
}
if err := client.DoTimeout(req, resp, time.Second); err == fasthttp.ErrPipelineOverflow {
    time.Sleep(10 * time.Millisecond) // backoff and retry
}

if client.MaxConns <= 0 { client.MaxConns = fasthttp.DefaultMaxConnsPerHost }
if client.MaxPendingRequests <= 0 { client.MaxPendingRequests = fasthttp.DefaultMaxPendingRequests }
if inFlight >= client.MaxConns*client.MaxPendingRequests { /* throttle before Do */ }

err := pc.DoTimeout(req, resp, timeout)
if errors.Is(err, fasthttp.ErrPipelineOverflow) {
    time.Sleep(backoff)
    goto retry
}

When it happens

Trigger: Calling PipelineClient.Do* while len(connClients) * MaxPendingRequests requests are already queued and none of the servers has consumed pending responses fast enough; e.g. a slow pipelined backend plus more DefaultMaxPendingRequests (1024) outstanding requests per connection.

Common situations: Bursty workloads sending thousands of pipelined requests to a slow server; misconfigured PipelineClient left at MaxConns=1/DefaultMaxPendingRequests defaults; request/response desynchronization where responses are read slower than requests are written.

Related errors

• pipeline connection has been stopped
• proxy: unknown scheme:
• dont support the network:
• fasthttp: cannot find whitespace in the first line of respon
• fasthttp: unexpected char at the end of status code

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