What causes ""samples" must be >= 1, but got ${JSON.stringify(r.samples)}" in remotion-dev/remotion?

Clamp samples to at least 1: `samples: Math.max(1, computedSamples)`.

remotion-dev/remotion · error · TypeError

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

Error message

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

What it means

After default resolution and type checks, the zoomBlur effect enforces a minimum of 1 on the `samples` parameter. If the resolved samples value is below 1 (including 0 or negative numbers), this TypeError is thrown. This is a range guard on top of the integer check.

Source

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

		throw new TypeError(
			`"${name}" must be an integer, but got ${JSON.stringify(value)}`,
		);
	}
};

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);

View on GitHub (pinned to 78fe4bb3fd)

Solutions

Clamp samples to at least 1: `samples: Math.max(1, computedSamples)`.
Use `interpolate(frame, [...], [1, 64], {extrapolateLeft: 'clamp', extrapolateRight: 'clamp'})` to keep the range valid.
Omit samples to use the default of 24.

Example fix

// before
zoomBlur({ samples: quality * 0 }); // 0 at low quality

// after
zoomBlur({ samples: Math.max(1, Math.round(quality * 24)) });

Defensive patterns

Strategy: validation

Validate before calling

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

Prevention

Clamp computed sample values to [1, 64] before passing.
Use interpolate with extrapolateLeft: 'clamp' for animated samples.
Avoid deriving samples from factors that can reach zero.

When it happens

Trigger: Passing `samples: 0`, `samples: -5`, or computing samples from a formula that can reach zero or negative (e.g., `Math.floor(intensity * 0)` when intensity is 0).

Common situations: Binding samples to a computed expression involving user-controlled intensity or quality settings that can bottom out at zero, or animating samples with interpolate() and hitting a negative value at the timeline edges.

Related errors

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