Factory limit "timeoutSeconds" must not exceed

Error message

Factory limit "timeoutSeconds" must not exceed ${MAX_FACTORY_TIMEOUT_SECONDS} seconds

What it means

validateLimits rejects timeoutSeconds values larger than MAX_FACTORY_TIMEOUT_SECONDS (2147483.647 seconds, i.e. 2^31-1 milliseconds) because timeouts are passed as 32-bit millisecond integers to the underlying runtime. Values beyond the cap would overflow the 32-bit signed integer range, so the library throws at definition time.

Solutions

Convert the value to seconds: divide millisecond values by 1000 before passing.
Use a value at or below 2147483.647 seconds.
Clamp or validate the configured timeout before calling defineFactory.
If a longer timeout is genuinely required, restructure the work instead of relying on a single factory timeout.

Example fix

// before
defineFactory({ name: 'build', limits: { timeoutSeconds: 600000 } }); // ms, not s
// after
defineFactory({ name: 'build', limits: { timeoutSeconds: 600 } });

Defensive patterns

Strategy: validation

Validate before calling

const MAX_FACTORY_TIMEOUT_SECONDS = 2147483.647;
if (t > MAX_FACTORY_TIMEOUT_SECONDS) throw new RangeError(`timeoutSeconds must be <= ${MAX_FACTORY_TIMEOUT_SECONDS}`);

Type guard

function withinMaxTimeout(t) { return t <= 2147483.647; }

Try / catch

try {
  defineFactory(meta);
} catch (e) {
  if (/must not exceed .* seconds/.test(e.message)) console.error('timeoutSeconds above 32-bit ms cap');
  throw e;
}

Prevention

Remember the field is seconds, not milliseconds — divide ms values by 1000
Share a single MAX_TIMEOUT constant across the codebase
Clamp configured timeouts to the cap before defining factories

When it happens

Trigger: Calling defineFactory with limits.timeoutSeconds greater than 2147483.647, e.g. passing milliseconds instead of seconds (timeoutSeconds: 300000 intending 5 minutes), or an absurdly large configured timeout.

Common situations: Unit confusion: developers who work with millisecond-based timeouts elsewhere (setTimeout) pass milliseconds into a seconds-based field; config values meant for other systems copied verbatim.

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.

Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

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

Appendix: source

Thrown at nodejs/src/factory.ts:444

        const value = limits[field];
        if (value !== undefined && (!Number.isInteger(value) || value <= 0)) {
            throw new Error(`Factory limit "${field}" must be a positive integer`);
        }
    }

    if (
        limits.timeoutSeconds !== undefined &&
        (!Number.isFinite(limits.timeoutSeconds) || limits.timeoutSeconds <= 0)
    ) {
        throw new Error(
            'Factory limit "timeoutSeconds" must be a positive, finite number of seconds'
        );
    }
    if (
        limits.timeoutSeconds !== undefined &&
        limits.timeoutSeconds > MAX_FACTORY_TIMEOUT_SECONDS
    ) {
        throw new Error(
            `Factory limit "timeoutSeconds" must not exceed ${MAX_FACTORY_TIMEOUT_SECONDS} seconds`
        );
    }

    if (limits.maxAiCredits !== undefined) {
        const maxNanoAiu = Math.round(limits.maxAiCredits * NANO_AIU_PER_AIU);
        if (
            !Number.isFinite(limits.maxAiCredits) ||
            limits.maxAiCredits <= 0 ||
            !Number.isSafeInteger(maxNanoAiu) ||
            maxNanoAiu < 1
        ) {
            throw new Error(
                'Factory limit "maxAiCredits" must be a positive, finite number that rounds to a safe positive integer nano-AIU ceiling'
            );
        }
    }
}

View on GitHub (pinned to cd8cf15dc3)