remotion-dev/remotion · error · TypeError

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

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.

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)

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.