{"record":{"id":"3fd4143ef434fb5f","repo":"panjf2000/ants","slug":"the-queue-is-full","errorCode":null,"errorMessage":"the queue is full","messagePattern":"the queue is full","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"worker_queue.go","lineNumber":31,"sourceCode":" *\n * THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n * SOFTWARE.\n */\n\npackage ants\n\nimport (\n\t\"errors\"\n\t\"time\"\n)\n\n// errQueueIsFull will be returned when the worker queue is full.\nvar errQueueIsFull = errors.New(\"the queue is full\")\n\ntype worker interface {\n\trun()\n\tfinish()\n\tlastUsedTime() int64\n\tsetLastUsedTime(t int64)\n\tinputFunc(func())\n\tinputArg(any)\n}\n\ntype workerQueue interface {\n\tlen() int\n\tisEmpty() bool\n\tinsert(worker) error\n\tdetach() worker\n\trefresh(duration time.Duration) []worker // clean up the stale workers and return them\n\treset()\n}","sourceCodeStart":13,"sourceCodeEnd":49,"githubUrl":"https://github.com/panjf2000/ants/blob/107e37678122b00e1b365636ce4f80623ba41579/worker_queue.go#L13-L49","documentation":"errQueueIsFull is a sentinel error returned by the rotated worker queue (loopQueue) when insert() is called and the queue has no free slots (wq.isFull is true). The pool uses this queue to hold idle workers; when it cannot accept a returned or new worker, it surfaces this error to the caller of insert. It is a normal, expected condition of a bounded queue, not a bug — callers are expected to handle it (e.g. the pool then blocks or discards the worker).","triggerScenarios":"Calling (*loopQueue).insert(worker) when the rotated queue already contains capacity() workers (wq.isFull == true). Internally triggered when a pool sized with a worker-loop queue tries to enqueue more idle workers than the queue capacity; the library's own test loops insert() until it returns errQueueIsFull.","commonSituations":"Pool created with a fixed worker capacity whose queue is saturated; bursty task submission exceeding MaxWorkerNum; callers of Pool.Tune or custom worker management inserting workers into a full rotated queue; misconfigured pool size smaller than concurrent submit rate.","solutions":["Increase the pool/queue capacity (pass a larger size to NewPool/NewMultiPool or Tune the pool) so the queue has room for the worker","Handle the sentinel error explicitly: compare with errors.Is(err, errQueueIsFull) and treat it as backpressure (skip insert, wait, or purge an idle worker first)","Check for leaked/busy workers: if workers are never recycled, tasks may be blocking; ensure submitted functions return and call worker.finish()","If implementing a custom worker queue, guard insert() with an isFull check before writing to items[tail]"],"exampleFix":"// before\nif err := pool.tuneQueue.Insert(worker); err != nil {\n    panic(err) // queue full at saturation\n}\n// after\nif err := pool.tuneQueue.Insert(worker); err != nil {\n    if errors.Is(err, errQueueIsFull) {\n        // expected backpressure: drop or retry later\n        return nil\n    }\n    return err\n}","handlingStrategy":"validation","validationCode":"if errors.Is(err, errQueueIsFull) { /* backpressure: queue at capacity, retry or skip */ }","typeGuard":null,"tryCatchPattern":"if err := q.insert(w); err != nil {\n    if errors.Is(err, errQueueIsFull) {\n        return nil // expected: queue saturated\n    }\n    return err\n}","preventionTips":["Size the pool so capacity comfortably exceeds peak concurrent workers","Treat errQueueIsFull as backpressure, never as a fatal error","Ensure tasks return promptly so workers recycle into the queue","Use Tune() to grow the pool under sustained load instead of inserting into a full queue"],"tags":["goroutine-pool","backpressure","queue-full","concurrency"],"backgroundTag":"value-out-of-range","analyzedSha":"107e37678122b00e1b365636ce4f80623ba41579","analyzedAt":"2026-09-06T13:28:28.492Z","contentChangedAt":"2026-09-06T13:28:28.492Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}