github/copilot-sdk · error

() accepts at most items; got .

Error message

${kind}() accepts at most ${MAX_FACTORY_FANOUT_ITEMS} items; got ${size}.

What it means

session.parallel() and session.pipeline() cap the number of concurrently fanned-out items at MAX_FACTORY_FANOUT_ITEMS (4096). assertFactoryFanoutSize is called by runFactoryParallel and runFactoryPipeline to reject oversized inputs before scheduling, protecting the session from unbounded promise allocation. It is a hard guardrail, not a transient condition.

Solutions

1. Split the input into chunks of at most 4096 and call parallel()/pipeline() per chunk, awaiting each batch.
2. Reduce fan-out by grouping related work into fewer thunks (e.g. process batches of items inside one thunk).
3. Queue overflow items and run them as earlier thunks complete.

Example fix

// before
const results = await session.parallel(files.map((f) => () => agent(f)));
// after
for (let i = 0; i < files.length; i += 4096) {
  const batch = files.slice(i, i + 4096).map((f) => () => agent(f));
  results.push(...(await session.parallel(batch)));
}

if (items.length > 4096) throw new Error(`Fan-out too large: ${items.length}; chunk into batches of <= 4096`);

try { await session.parallel(thunks); } catch (e) { if (String(e.message).includes('accepts at most')) chunkAndRetry(thunks); else throw e; }

When it happens

Trigger: Calling parallel(thunks) or pipeline(items, ...stages) with more than 4096 elements in the input array.

Common situations: Batching thousands of agent/tool invocations built from a large dataset (e.g. per-file or per-row work over a big directory or DB export) without chunking; loop-generated task arrays that grew with the codebase.

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

• FfiRuntimeHost was closed during startup.
• Interrupted while starting in-process runtime host.
• Interrupted while waiting for callback data

AI-assisted analysis of github/copilot-sdk@cd8cf15dc3 (2026-09-09). Data as JSON: /api/errors/6179b99c8ac3d616. Report an issue: GitHub.

Appendix: source

Thrown at nodejs/src/session.ts:168

        return false;
    }
    const instance = value as Partial<OpenCanvasInstance>;
    return (
        typeof instance.instanceId === "string" &&
        instance.instanceId.length > 0 &&
        typeof instance.extensionId === "string" &&
        instance.extensionId.length > 0 &&
        typeof instance.canvasId === "string" &&
        instance.canvasId.length > 0
    );
}

const FACTORY_LOG_FLUSH_DELAY_MS = 10;
const MAX_FACTORY_FANOUT_ITEMS = 4096;

function assertFactoryFanoutSize(kind: "parallel" | "pipeline", size: number): void {
    if (size > MAX_FACTORY_FANOUT_ITEMS) {
        throw new Error(
            `${kind}() accepts at most ${MAX_FACTORY_FANOUT_ITEMS} items; got ${size}.`
        );
    }
}

async function runFactoryParallel<TResult>(
    thunks: Array<() => Promise<TResult> | TResult>
): Promise<Array<TResult | null>> {
    if (!Array.isArray(thunks)) {
        throw new Error(
            "parallel() expects an array of functions, not promises. Wrap each call: () => agent(...)"
        );
    }
    assertFactoryFanoutSize("parallel", thunks.length);
    if (thunks.some((thunk) => typeof thunk !== "function")) {
        throw new Error(
            "parallel() expects an array of functions, not promises. Wrap each call: () => agent(...)"
        );

View on GitHub (pinned to cd8cf15dc3)