What causes "nested factories are not supported" in github/copilot-sdk?

Flatten the nested factory: inline its logic into the parent factory's run function

nested factories are not supported

Error message

nested factories are not supported

What it means

Inside a factory execution context, the injected `factory` helper is intentionally stubbed to always throw, because the SDK does not support spawning a factory from within another factory's run function. Nesting factory executions is disallowed to keep the execution store single, unambiguous.

Solutions

Flatten the nested factory: inline its logic into the parent factory's run function
Extract shared logic into a plain async function or use `parallel`/`pipeline` helpers instead of factory.execute
Run the sub-factory as a separate top-level execution outside the parent factory context

Example fix

// before
await myFactory.run({
  run: async (ctx) => {
    await ctx.factory.execute({ name: "inner" }); // throws
  }
});
// after
await myFactory.run({
  run: async (ctx) => {
    await ctx.pipeline([stepCompile, stepTest]); // use pipeline/parallel or inline logic
  }
});

Defensive patterns

Strategy: validation

Validate before calling

if (factoryExecutionStore.isActive?.()) throw new Error("already inside a factory; do not call factory.execute");

Try / catch

try {
  await ctx.factory.execute({ name });
} catch (err) {
  if (err?.message === "nested factories are not supported") {
    throw new Error("Refactor: inline the sub-factory or run it outside this factory context");
  }
  throw err;
}

Prevention

Treat factories as top-level units; compose with pipeline/parallel instead of nesting
Extract shared step logic into plain functions callable from any factory
Document that factory.execute is only valid outside factory.run

When it happens

Trigger: Calling `factory.execute(...)` (or equivalent) from inside a factory definition's `run` function; composing factories by invoking one factory from another's context.

Common situations: Refactoring monolithic factories into nested sub-factories; trying to build hierarchical workflow composition; reusing an existing factory as a step of a new factory.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

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

Appendix: source

Thrown at nodejs/src/session.ts:1567

                            // concurrent callers, so authors must make side effects idempotent.
                            const result = await producer();
                            assertFactoryStepResult(result, key);
                            await awaitFactoryOperation(
                                () =>
                                    self.rpc.factory.journal.put({
                                        runId: params.runId,
                                        executionToken: params.executionToken,
                                        key,
                                        resultJson: result,
                                    }),
                                controller.signal
                            );
                            return result;
                        },
                        parallel: runFactoryParallel,
                        pipeline: runFactoryPipeline,
                        factory: async () => {
                            throw new Error("nested factories are not supported");
                        },
                    };
                    const execution = { active: true };
                    const result = await factoryExecutionStore.run(execution, async () => {
                        try {
                            return await definition.run(context);
                        } finally {
                            execution.active = false;
                        }
                    });
                    if (result === undefined) {
                        return {};
                    }
                    assertFactoryResult(result);
                    return { result };
                } finally {
                    try {
                        await progress.close();

View on GitHub (pinned to cd8cf15dc3)