remotion-dev/remotion · error · TypeError

"samples" must be <= ${MAX_SAMPLES}, but got ${JSON.stringif

Error message

"samples" must be <= ${MAX_SAMPLES}, but got ${JSON.stringify(r.samples)}

What it means

The zoomBlur effect caps `samples` at a compile-time constant `MAX_SAMPLES` (64). Higher sample counts increase GPU cost proportionally; this guard prevents excessive GPU work that would degrade rendering performance. If the resolved samples value exceeds 64, this TypeError is thrown.

Source

Thrown at packages/effects/src/zoom-blur/index.ts:117

const validateZoomBlurParams = (params: ZoomBlurParams): void => {
	assertEffectParamsObject(params, 'Zoom Blur');
	assertOptionalFiniteNumber(params.amount, 'amount');
	assertOptionalUvCoordinate(params.center, 'center');
	assertOptionalFiniteNumber(params.samples, 'samples');
	assertOptionalInteger(params.samples, 'samples');

	const r = resolve(params);
	validateNonNegative(r.amount, 'amount');
	validateUnitInterval(r.center[0], 'center[0]');
	validateUnitInterval(r.center[1], 'center[1]');
	if (r.samples < 1) {
		throw new TypeError(
			`"samples" must be >= 1, but got ${JSON.stringify(r.samples)}`,
		);
	}

	if (r.samples > MAX_SAMPLES) {
		throw new TypeError(
			`"samples" must be <= ${MAX_SAMPLES}, but got ${JSON.stringify(r.samples)}`,
		);
	}
};

export const zoomBlur = createEffect<ZoomBlurParams, ZoomBlurState>({
	type: 'remotion/zoom-blur',
	label: 'zoomBlur()',
	documentationLink: 'https://www.remotion.dev/docs/effects/zoom-blur',
	backend: 'webgl2',
	calculateKey: (params) => {
		const r = resolve(params);
		return `zoom-blur-${r.amount}-${r.center[0]}-${r.center[1]}-${r.samples}`;
	},
	setup: (target) => setupZoomBlur(target),
	apply: ({source, width, height, params, state, flipSourceY}) => {
		const r = resolve(params);
		applyZoomBlur({

View on GitHub (pinned to 78fe4bb3fd)

Solutions

1. Clamp to the maximum: `samples: Math.min(64, computedSamples)`.
2. Use `interpolate(frame, [...], [1, 64], {extrapolateRight: 'clamp'})`.
3. Omit samples to use the default of 24.

Example fix

// before
zoomBlur({ samples: qualityFactor * 100 }); // can exceed 64

// after
zoomBlur({ samples: Math.min(64, Math.max(1, Math.round(qualityFactor * 64))) });

const MAX_SAMPLES = 64;
const samples = Math.min(MAX_SAMPLES, Math.max(1, Math.round(computedSamples)));
zoomBlur({ samples });

When it happens

Trigger: Passing `samples: 100`, `samples: 128`, or an interpolated value that overshoots the cap. Also triggered by multiplying a base count by a scaling factor that exceeds 64.

Common situations: A quality slider mapped to a wide range, animation interpolation without clamping, or copying a high sample count from a different effect with a higher cap.

Related errors

• "samples" must be >= 1, but got ${JSON.stringify(r.samples)}
• "${name}" must be a [number, number] tuple
• "${name}" must be an integer, but got ${JSON.stringify(value
• The "width" and "height" props must be numbers on <Img> when
• The ${formatPropList(conflictingProps)} prop${conflictingPro

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