What causes "invalid pool index" in panjf2000/ants?

Validate the index before calling: ensure 0 <= idx < the size passed to NewMultiPool*.

panjf2000/ants · error

invalid pool index

Error message

invalid pool index

What it means

ErrInvalidPoolIndex is returned by MultiPool index-based accessors such as WaitingByIndex and RunningByIndex when the given index is outside the range [0, len(pools)). It is an argument-validation error protecting against out-of-bounds pool lookups on a MultiPool.

Source

Thrown at ants.go:82

	ErrLackPoolFunc = errors.New("must provide function for pool")

	// ErrInvalidPoolExpiry will be returned when setting a negative number as the periodic duration to purge goroutines.
	ErrInvalidPoolExpiry = errors.New("invalid expiry for pool")

	// ErrPoolClosed will be returned when submitting task to a closed pool.
	ErrPoolClosed = errors.New("this pool has been closed")

	// ErrPoolOverload will be returned when the pool is full and no workers available.
	ErrPoolOverload = errors.New("too many goroutines blocked on submit or Nonblocking is set")

	// ErrInvalidPreAllocSize will be returned when trying to set up a negative capacity under PreAlloc mode.
	ErrInvalidPreAllocSize = errors.New("can not set up a negative capacity under PreAlloc mode")

	// ErrTimeout will be returned after the operations timed out.
	ErrTimeout = errors.New("operation timed out")

	// ErrInvalidPoolIndex will be returned when trying to retrieve a pool with an invalid index.
	ErrInvalidPoolIndex = errors.New("invalid pool index")

	// ErrInvalidLoadBalancingStrategy will be returned when trying to create a MultiPool with an invalid load-balancing strategy.
	ErrInvalidLoadBalancingStrategy = errors.New("invalid load-balancing strategy")

	// ErrInvalidMultiPoolSize  will be returned when trying to create a MultiPool with an invalid size.
	ErrInvalidMultiPoolSize = errors.New("invalid size for multiple pool")

	// workerChanCap determines whether the channel of a worker should be a buffered channel
	// to get the best performance. Inspired by fasthttp at
	// https://github.com/valyala/fasthttp/blob/master/workerpool.go#L139
	workerChanCap = func() int {
		// Use blocking channel if GOMAXPROCS=1.
		// This switches context from sender to receiver immediately,
		// which results in higher performance (under go1.5 at least).
		if runtime.GOMAXPROCS(0) == 1 {
			return 0
		}

View on GitHub (pinned to 107e376781)

Solutions

Validate the index before calling: ensure 0 <= idx < the size passed to NewMultiPool*.
Reduce sharding keys with modulo the actual pool count.
If you only need totals, use mp.Waiting()/mp.Running() instead of per-index lookups.

Example fix

// before
w, err := mp.WaitingByIndex(shardID)
// after
idx := int(shardID) % poolSize
if idx < 0 {
    idx += poolSize
}
w, err := mp.WaitingByIndex(idx)

Defensive patterns

Strategy: validation

Validate before calling

func validIndex(idx, poolSize int) bool {
    return idx >= 0 && idx < poolSize
}
if !validIndex(i, poolCount) {
    return fmt.Errorf("pool index %d out of range [0,%d)", i, poolCount)
}

Try / catch

if _, err := mp.WaitingByIndex(i); errors.Is(err, ants.ErrInvalidPoolIndex) {
    i = 0 // or return a config error
}

Prevention

Keep the MultiPool size in a variable and compute indices as idx %% size.
Never hard-code sub-pool indices; iterate over [0, size).
Use mp.Waiting()/mp.Running() aggregates when per-index detail is unnecessary.

When it happens

Trigger: mp.WaitingByIndex(-1) or mp.WaitingByIndex(11) when the MultiPool was created with fewer than 12 sub-pools; similarly RunningByIndex with an out-of-range index.

Common situations: Computing an index from a hash/shard key without modding by the pool count; hard-coded indices that drift from the configured pool size; iterating with wrong bounds.

Related errors

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