remotion-dev/remotion · error · TypeError

maxRetries must be a number, but is ${JSON.stringify(maxRetr

Error message

maxRetries must be a number, but is ${JSON.stringify(maxRetries)}

What it means

Thrown by validateMaxRetries() (a TypeError) when the maxRetries value passed to the Lambda render/still CLI flow is not a number. The function is an assertion (`asserts maxRetries is number`) used by the render and still CLI commands.

Source

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

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(

View on GitHub (pinned to 78fe4bb3fd)

Solutions

1. Pass a finite non-negative integer number.
2. Convert env/CLI string values with Number() (and guard emptiness) before passing.
3. Use the TypeScript signature so the compiler enforces number.

Example fix

// before
renderMediaOnLambda({..., maxRetries: process.env.MAX_RETRIES})
// after
const maxRetries = process.env.MAX_RETRIES ? Number(process.env.MAX_RETRIES) : 1
renderMediaOnLambda({..., maxRetries})

if (typeof maxRetries !== 'number') {
  throw new TypeError(`maxRetries must be a number, got ${typeof maxRetries}`)
}

const isMaxRetries = (v: unknown): v is number =>
  typeof v === 'number' && Number.isInteger(v) && v >= 0

When it happens

Trigger: Passing maxRetries from an env var (string), a CLI flag parsed as string, undefined, or an object into renderMediaOnLambda/renderStillOnLambda or the CLI.

Common situations: Reading --max-retries from a custom wrapper without Number(); config files where the value is a string; passing undefined unintentionally.

Related errors

• A custom role ARN must either be "undefined" or a string, bu
• CloudWatch retention period should be a number, got: ${JSON.
• CloudWatch retention period must be an integer, but is NaN
• maxRetries must be finite, but is ${maxRetries}
• parameter 'vpcSecurityGroupIds' must either be 'undefined' o

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