apify/crawlee · error · Error

Chunk size must be a positive number (${inspect(chunkSize)})

Error message

Chunk size must be a positive number (${inspect(chunkSize)}) received

What it means

chunkedAsyncIterable groups items from an (async) iterable into arrays of a given size. When a numeric chunkSize less than 1 is passed, the library throws immediately because chunk sizes below 1 would loop forever. Function-typed chunk sizes bypass this numeric check.

Source

Thrown at packages/core/src/iterables.ts:47

 * **Example usage:**
 * ```ts
 * const numbers = async function* () {
 *   for (let i = 1; i <= 10; i++) yield i;
 * };
 *
 * for await (const chunk of chunkedAsyncIterable(numbers(), 3)) {
 *   console.log(chunk); // [1, 2, 3], [4, 5, 6], [7, 8, 9], [10]
 * }
 * ```
 */
export async function* chunkedAsyncIterable<T>(
    iterable: AsyncIterable<T> | Iterable<T>,
    chunkSize: number | (() => number),
): AsyncIterable<T[]> {
    const getChunkSize = typeof chunkSize === 'function' ? chunkSize : () => chunkSize;

    if (typeof chunkSize === 'number' && chunkSize < 1) {
        throw new Error(`Chunk size must be a positive number (${inspect(chunkSize)}) received`);
    }

    const iterator =
        Symbol.asyncIterator in iterable
            ? (iterable as AsyncIterable<T>)[Symbol.asyncIterator]()
            : (iterable as Iterable<T>)[Symbol.iterator]();

    while (true) {
        const currentSize = getChunkSize();
        if (currentSize < 1) break;

        const chunk: T[] = [];

        for (let i = 0; i < currentSize; i++) {
            const next = await iterator.next();
            if (next.done) {
                break;
            }

View on GitHub (pinned to dbe57fb09c)

Solutions

Pass a chunkSize >= 1 (integer)
Clamp computed values: Math.max(1, value)
If using a function form, validate its return values yourself
Fall back to a sane default when config is missing

Example fix

// before
const size = Number(process.env.BATCH); iterable(chunked(items, size));
// after
const size = Math.max(1, Number(process.env.BATCH) || 10); iterable(chunked(items, size));

Defensive patterns

Strategy: validation

Validate before calling

const size = Number(chunkSize);
if (!Number.isFinite(size) || size < 1) throw new Error(`chunkSize must be >= 1, got ${chunkSize}`);

Type guard

const isValidChunkSize = (n: unknown): n is number => typeof n === 'number' && Number.isFinite(n) && n >= 1;

Prevention

Clamp computed batch sizes with Math.max(1, v)
Validate env-derived numbers before use
Remember function-form chunkSize skips this check - validate its return values

When it happens

Trigger: Calling chunks()/chunked()/chunkedAsyncIterable with chunkSize = 0, a negative number, or NaN from computed config values.

Common situations: batchSize derived from env vars that default to 0; off-by-one or float computations (e.g. Math.floor of 0.x); passing a function that returns invalid sizes (not validated here).

Related errors

AI-assisted analysis of apify/crawlee@dbe57fb09c (2026-08-30). Data as JSON: /api/errors/e4aa6eb92fa3430d. Report an issue: GitHub.