{"record":{"id":"906d7e74041e31c8","repo":"valyala/fasthttp","slug":"fasthttp-pipelined-requests-queue-has-been-overf","errorCode":null,"errorMessage":"fasthttp: pipelined requests' queue has been overflowed. increase maxconns and/or maxpendingrequests","messagePattern":"fasthttp: pipelined requests' queue has been overflowed\\. increase maxconns and/or maxpendingrequests","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"client.go","lineNumber":2993,"sourceCode":"\t\tDialDualStack:                 c.DialDualStack,\n\t\tDisableHeaderNamesNormalizing: c.DisableHeaderNamesNormalizing,\n\t\tDisablePathNormalizing:        c.DisablePathNormalizing,\n\t\tIsTLS:                         c.IsTLS,\n\t\tTLSConfig:                     c.TLSConfig,\n\t\tMaxIdleConnDuration:           c.MaxIdleConnDuration,\n\t\tReadBufferSize:                c.ReadBufferSize,\n\t\tWriteBufferSize:               c.WriteBufferSize,\n\t\tReadTimeout:                   c.ReadTimeout,\n\t\tWriteTimeout:                  c.WriteTimeout,\n\t\tLogger:                        c.Logger,\n\t}\n\tc.connClients = append(c.connClients, cc)\n\treturn cc\n}\n\n// ErrPipelineOverflow may be returned from PipelineClient.Do*\n// if the requests' queue is overflowed.\nvar ErrPipelineOverflow = errors.New(\"fasthttp: pipelined requests' queue has been overflowed. \" +\n\t\"increase maxconns and/or maxpendingrequests\")\n\n// DefaultMaxPendingRequests is the default value\n// for PipelineClient.MaxPendingRequests.\nconst DefaultMaxPendingRequests = 1024\n\nfunc (c *pipelineConnClient) acquirePipelineConnChannels() *pipelineConnChannels {\n\tc.chLock.Lock()\n\tchs := c.chs\n\tif chs == nil {\n\t\tmaxPendingRequests := c.MaxPendingRequests\n\t\tif maxPendingRequests <= 0 {\n\t\t\tmaxPendingRequests = DefaultMaxPendingRequests\n\t\t}\n\t\tchs = &pipelineConnChannels{\n\t\t\tchR: make(chan *pipelineWork, maxPendingRequests),\n\t\t\tchW: make(chan *pipelineWork, maxPendingRequests),\n\t\t}","sourceCodeStart":2975,"sourceCodeEnd":3011,"githubUrl":"https://github.com/valyala/fasthttp/blob/c96f600972c6f4a7a30d664257b340ebe9d60124/client.go#L2975-L3011","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Increase PipelineClient.MaxConns so requests spread over more pipeline connections","Increase PipelineClient.MaxPendingRequests to enlarge each connection's queue","Throttle callers (limit in-flight Do* calls) and retry on ErrPipelineOverflow with backoff","Investigate why the server responds slowly / out of order over the pipeline"],"exampleFix":"// before\nclient := &fasthttp.PipelineClient{}\nfor _, req := range reqs { client.Do(req, resp) }\n// after\nclient := &fasthttp.PipelineClient{\n    MaxConns:            16,\n    MaxPendingRequests:  8192,\n}\nif err := client.DoTimeout(req, resp, time.Second); err == fasthttp.ErrPipelineOverflow {\n    time.Sleep(10 * time.Millisecond) // backoff and retry\n}","handlingStrategy":"retry","validationCode":"if client.MaxConns <= 0 { client.MaxConns = fasthttp.DefaultMaxConnsPerHost }\nif client.MaxPendingRequests <= 0 { client.MaxPendingRequests = fasthttp.DefaultMaxPendingRequests }\nif inFlight >= client.MaxConns*client.MaxPendingRequests { /* throttle before Do */ }","typeGuard":null,"tryCatchPattern":"err := pc.DoTimeout(req, resp, timeout)\nif errors.Is(err, fasthttp.ErrPipelineOverflow) {\n    time.Sleep(backoff)\n    goto retry\n}","preventionTips":["Size MaxConns to your concurrency level","Size MaxPendingRequests above worst-case burst","Apply client-side rate limiting/throttling","Monitor queue depth and back off reactively"],"tags":["fasthttp","pipelining","backpressure","network"],"backgroundTag":"pipeline-queue-overflow","analyzedSha":"c96f600972c6f4a7a30d664257b340ebe9d60124","analyzedAt":"2026-08-31T22:48:28.265Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T05:18:18.240Z"}