What causes "maxRetries cannot be negative but is ${maxRetries}" in remotion-dev/remotion?

Set maxRetries to 0 if you want no retries, or to a positive integer (typically 1-3).

remotion-dev/remotion · error · TypeError

maxRetries cannot be negative but is ${maxRetries}

Error message

maxRetries cannot be negative but is ${maxRetries}

What it means

Thrown by validateMaxRetries() in @remotion/lambda when maxRetries is a real number but negative. maxRetries is the count of retry attempts the Lambda CLI applies to a failing render/still; a negative count is meaningless. Unlike the NaN case, this check is reachable because Number.isFinite(-1) is true.

Source

Thrown at packages/lambda/src/shared/validate-retries.ts:19

export function validateMaxRetries(
	maxRetries: unknown,
): asserts maxRetries is number {
	if (typeof maxRetries !== 'number') {
		throw new TypeError(
			'maxRetries must be a number, but is ' + JSON.stringify(maxRetries),
		);
	}

	if (!Number.isFinite(maxRetries)) {
		throw new TypeError('maxRetries must be finite, but is ' + maxRetries);
	}

	if (Number.isNaN(maxRetries)) {
		throw new TypeError('maxRetries is NaN');
	}

	if (maxRetries < 0) {
		throw new TypeError(`maxRetries cannot be negative but is ${maxRetries}`);
	}

	if (maxRetries % 1 !== 0) {
		throw new TypeError(
			`maxRetries should be an integer, but is ${maxRetries}.`,
		);
	}
}

View on GitHub (pinned to 78fe4bb3fd)

Solutions

Set maxRetries to 0 if you want no retries, or to a positive integer (typically 1-3).
Clamp computed values: const maxRetries = Math.max(0, computed);
Re-check the source of the negative value; it usually indicates a wrong formula upstream.

Example fix

// before
const maxRetries = quota - attemptsMade; // can be negative

// after
const maxRetries = Math.max(0, quota - attemptsMade);

Defensive patterns

Strategy: validation

Validate before calling

const maxRetries = Math.max(0, Number.isFinite(parsed) ? Math.floor(parsed) : DEFAULT_MAX_RETRIES);

Type guard

const isNonNegativeInteger = (v: unknown): v is number =>
  typeof v === 'number' && Number.isFinite(v) && v >= 0 && v % 1 === 0;

Prevention

Clamp any computed retry count to >= 0 before passing it.
Use 0 to mean 'no retries' rather than a negative sentinel.
Audit formulas that subtract attempts from a quota for underflow.

When it happens

Trigger: Passing a negative integer to renderMediaOnLambda()/renderStillOnLambda() maxRetries, or `npx remotion lambda render --max-retries=-1`. Common when the value is computed as a delta that goes negative (e.g. retries = limit - attempts).

Common situations: Subtracting from a quota/base to derive retries and underflowing past zero; copying a config where retries was set as 'minus one for the first attempt'; typo in env var.

Related errors

AI-assisted analysis of remotion-dev/remotion@78fe4bb3fd (2026-08-12). Data as JSON: /api/errors/5a2fd76e67d990ca. Report an issue: GitHub.