remotion-dev/remotion · error · TypeError

" " must be <= , but got

Error message

"${name}" must be <= ${max}, but got ${JSON.stringify(value)}

What it means

Thrown by validateAtMost (packages/effects/src/paper.ts:271), reached from validatePaperParams for the upper-bound checks on fiberSize/crumpleSize (max 1 via validatePositiveUnitInterval), foldCount (max 15), seed (max 1000), and scale (max 4). It fires when the resolved value exceeds the documented maximum for that parameter.

Solutions

  1. Clamp the offending param to its max: fiberSize/crumpleSize ≤ 1, foldCount ≤ 15, seed ≤ 1000, scale ≤ 4.
  2. When animating, use interpolate(..., {extrapolateLeft: 'clamp', extrapolateRight: 'clamp'}) so values never exceed bounds.
  3. Validate deserialized params with the guard below before passing them to paper().

Example fix

// before
paper({foldCount: 20, seed: 5000}); // throws

// after
paper({foldCount: 15, seed: 1000});
Defensive patterns

Strategy: validation

Validate before calling

// Validate paper params against the documented maxima before calling paper()
const PAPER_MAX = {fiberSize: 1, crumpleSize: 1, foldCount: 15, seed: 1000, scale: 4};

function withinPaperMax(p: Partial<Record<keyof typeof PAPER_MAX, number>>): boolean {
  return (Object.keys(PAPER_MAX) as (keyof typeof PAPER_MAX)[]).every((k) => {
    const v = p[k];
    return v === undefined || v <= PAPER_MAX[k];
  });
}

function clampPaperMax<T extends Partial<Record<keyof typeof PAPER_MAX, number>>>(p: T): T {
  const out = {...p} as T;
  (Object.keys(PAPER_MAX) as (keyof typeof PAPER_MAX)[]).forEach((k) => {
    if (out[k] !== undefined) (out as Record<string, number>)[k] = Math.min(out[k] as number, PAPER_MAX[k]);
  });
  return out;
}

Type guard

const isWithinPaperMax = (p: unknown): boolean => {
  if (typeof p !== 'object' || p === null) return false;
  const o = p as Record<string, unknown>;
  return (['fiberSize','crumpleSize','foldCount','seed','scale'] as const).every((k) =>
    o[k] === undefined || (typeof o[k] === 'number' && o[k] <= PAPER_MAX[k]));
};

Try / catch

try {
  paper(raw);
} catch (err) {
  if (err instanceof TypeError && /must be <=/.test(err.message)) {
    paper(clampPaperMax(raw)); // clamp and retry
  } else throw err;
}

Prevention

When it happens

Trigger: Calling paper({fiberSize: 1.5}), paper({crumpleSize: 2}), paper({foldCount: 20}), paper({seed: 5000}), or paper({scale: 5}); any resolved param above its declared max.

Common situations: Copying values from a design tool whose scale/seed ranges differ; animating a param with interpolate that overshoots its target; UI sliders configured with a wider range than the effect allows.

Related errors

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

Appendix: source

Thrown at packages/effects/src/paper.ts:271

	colorFront: p.colorFront ?? DEFAULT_COLOR_FRONT,
	colorBack: p.colorBack ?? DEFAULT_COLOR_BACK,
	contrast: p.contrast ?? DEFAULT_CONTRAST,
	roughness: p.roughness ?? DEFAULT_ROUGHNESS,
	fiber: p.fiber ?? DEFAULT_FIBER,
	fiberSize: p.fiberSize ?? DEFAULT_FIBER_SIZE,
	crumples: p.crumples ?? DEFAULT_CRUMPLES,
	crumpleSize: p.crumpleSize ?? DEFAULT_CRUMPLE_SIZE,
	folds: p.folds ?? DEFAULT_FOLDS,
	foldCount: p.foldCount ?? DEFAULT_FOLD_COUNT,
	drops: p.drops ?? DEFAULT_DROPS,
	fade: p.fade ?? DEFAULT_FADE,
	seed: p.seed ?? DEFAULT_SEED,
	scale: p.scale ?? DEFAULT_SCALE,
});

const validateAtMost = (value: number, max: number, name: string): void => {
	if (value > max) {
		throw new TypeError(
			`"${name}" must be <= ${max}, but got ${JSON.stringify(value)}`,
		);
	}
};

const validatePositiveUnitInterval = (value: number, name: string): void => {
	if (value <= 0) {
		throw new TypeError(
			`"${name}" must be greater than 0, but got ${JSON.stringify(value)}`,
		);
	}

	validateAtMost(value, 1, name);
};

const validatePaperParams = (params: PaperParams): void => {
	assertEffectParamsObject(params, 'Paper');
	assertOptionalFiniteNumber(params.amount, 'amount');

View on GitHub (pinned to 78fe4bb3fd)