panjf2000/ants · error

can not set up a negative capacity under PreAlloc mode

Error message

can not set up a negative capacity under PreAlloc mode

What it means

ErrInvalidPreAllocSize is returned when PreAlloc mode is requested with capacity -1. Under PreAlloc, ants pre-allocates the worker slice at construction, so the size must be a concrete non-negative value; infinite capacity (-1) cannot be pre-allocated (ants.go:235).

Source

Thrown at ants.go:76

	// CLOSED represents that the pool is closed.
	CLOSED
)

var (
	// ErrLackPoolFunc will be returned when invokers don't provide function for pool.
	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.

View on GitHub (pinned to 107e376781)

Solutions

1. Provide a finite positive capacity when using WithPreAlloc(true).
2. If you truly need an unbounded pool, drop WithPreAlloc (PreAlloc only helps with a known capacity).
3. Clamp config-derived sizes: if size <= 0 and PreAlloc is enabled, choose a default capacity.

Example fix

// before
pool, err := ants.NewPool(-1, ants.WithPreAlloc(true))
// after
pool, err := ants.NewPool(10000, ants.WithPreAlloc(true))

if size < 0 && preAlloc {
    return fmt.Errorf("PreAlloc requires a finite capacity, got %d", size)
}

When it happens

Trigger: ants.NewPool(-1, ants.WithPreAlloc(true)) or the WithFunc/Generic equivalents passing size -1 together with WithPreAlloc(true).

Common situations: Reusing a shared 'size = -1 means unlimited' idiom from non-prealloc code and adding PreAlloc for performance; size derived from config defaulting to -1.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• invalid expiry for pool
• invalid size for multiple pool
• must provide function for pool
• invalid pool index
• invalid load-balancing strategy

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