panjf2000/ants · warning

the queue is full

Error message

the queue is full

What it means

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).

Source

Thrown at worker_queue.go:31

 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 * SOFTWARE.
 */

package ants

import (
	"errors"
	"time"
)

// errQueueIsFull will be returned when the worker queue is full.
var errQueueIsFull = errors.New("the queue is full")

type worker interface {
	run()
	finish()
	lastUsedTime() int64
	setLastUsedTime(t int64)
	inputFunc(func())
	inputArg(any)
}

type workerQueue interface {
	len() int
	isEmpty() bool
	insert(worker) error
	detach() worker
	refresh(duration time.Duration) []worker // clean up the stale workers and return them
	reset()
}

View on GitHub (pinned to 107e376781)

Solutions

1. Increase the pool/queue capacity (pass a larger size to NewPool/NewMultiPool or Tune the pool) so the queue has room for the worker
2. 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)
3. Check for leaked/busy workers: if workers are never recycled, tasks may be blocking; ensure submitted functions return and call worker.finish()
4. If implementing a custom worker queue, guard insert() with an isFull check before writing to items[tail]

Example fix

// before
if err := pool.tuneQueue.Insert(worker); err != nil {
    panic(err) // queue full at saturation
}
// after
if err := pool.tuneQueue.Insert(worker); err != nil {
    if errors.Is(err, errQueueIsFull) {
        // expected backpressure: drop or retry later
        return nil
    }
    return err
}

if errors.Is(err, errQueueIsFull) { /* backpressure: queue at capacity, retry or skip */ }

if err := q.insert(w); err != nil {
    if errors.Is(err, errQueueIsFull) {
        return nil // expected: queue saturated
    }
    return err
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• too many goroutines blocked on submit or Nonblocking is set
• this pool has been closed
• operation timed out

AI-assisted analysis of panjf2000/ants@107e376781 (2026-09-06). Data as JSON: /api/errors/3fd4143ef434fb5f. Report an issue: GitHub.