remotion-dev/remotion · error · TypeError

maxRetries should be an integer, but is ${maxRetries}.

Error message

maxRetries should be an integer, but is ${maxRetries}.

What it means

Thrown by validateMaxRetries() in @remotion/lambda when maxRetries is a finite number but not an integer (the % 1 !== 0 check). Lambda cannot perform a fractional retry, so the validator requires an integer.

Source

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

		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

1. Round to the nearest integer: Math.round(maxRetries) (or Math.floor / Math.ceil to bias down/up).
2. Fix the upstream calculation so it yields an integer count, not a ratio.
3. If the decimal is from a config file, change the config value to an integer.

Example fix

// before
const maxRetries = totalRetries / parallelism; // e.g. 3 / 2 = 1.5

// after
const maxRetries = Math.round(totalRetries / parallelism);

const maxRetries = Math.round(Number(raw));
if (!Number.isInteger(maxRetries) || maxRetries < 0) throw new Error('invalid maxRetries');

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

When it happens

Trigger: Passing a float like 1.5 or 2.1 to renderMediaOnLambda()/renderStillOnLambda() maxRetries, or `--max-retries=1.5` on the CLI. Often comes from dividing retries across parallel functions (e.g. totalRetries / parallelism).

Common situations: Computing retries from a ratio (retries = baseConcurrency * 0.5), reading a decimal from a JSON config, or accidentally using a percentage as a count.

Related errors

• maxRetries is NaN
• maxRetries cannot be negative but is ${maxRetries}
• Pass --s3-output-provider-endpoint when using S3 output prov
• Pass --force-bucket-name when using S3 output provider flags
• Pass --out-name when using S3 output provider flags.

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