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

Q: What causes ""${name}" must be <= 1, but got ${JSON.stringify(value)}" in remotion-dev/remotion?

Clamp the value to [0,1]: Math.max(0, Math.min(1, value)).

remotion-dev/remotion · error · TypeError

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

Error message

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

What it means

Thrown by validateUnitInterval in color-utils.ts when a value resolved to the [0,1] range exceeds 1. The dynamic name identifies the offending field: 'pivot' for color-correction, or 'similarity'/'smoothness'/'spillSuppression' for color-key. It is a caller-input TypeError.

Source

Thrown at packages/effects/src/color-utils.ts:63

	value: unknown,
	name: string,
): void => {
	if (value === undefined) {
		return;
	}

	assertRequiredFiniteNumber(value, name);
};

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

	if (value > 1) {
		throw new TypeError(
			`"${name}" must be <= 1, but got ${JSON.stringify(value)}`,
		);
	}
};

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

export const validateSignedUnitInterval = (
	value: number,
	name: string,
): void => {
	if (value < -1) {

View on GitHub (pinned to 78fe4bb3fd)

Solutions

Clamp the value to [0,1]: Math.max(0, Math.min(1, value)).
Use interpolate(..., {extrapolateLeft: 'clamp', extrapolateRight: 'clamp'}) so animation cannot exceed the range.
Inspect the field name and value in the error and fix the source number.
Omit the field to use its documented default.

Example fix

// before
colorCorrection({pivot: 1.4}); // throws: pivot must be <= 1

// after
const pivot = Math.max(0, Math.min(1, animated));
colorCorrection({pivot});

Defensive patterns

Strategy: validation

Validate before calling

function assertUnitInterval(value: number | undefined, name: string): number | undefined {
  if (value === undefined) return value;
  if (!Number.isFinite(value)) {
    throw new TypeError(`${name} must be finite, got ${value}`);
  }
  if (value < 0 || value > 1) {
    throw new TypeError(`${name} must be in [0, 1], got ${value}`);
  }
  return value;
}

// colorCorrection({pivot: assertUnitInterval(pivot, 'pivot')})
// colorKey({
//   similarity: assertUnitInterval(sim, 'similarity'),
//   smoothness: assertUnitInterval(smooth, 'smoothness'),
//   spillSuppression: assertUnitInterval(spill, 'spillSuppression'),
// })

Type guard

const isUnitInterval = (v: unknown): v is number =>
  typeof v === 'number' && Number.isFinite(v) && v >= 0 && v <= 1;

Prevention

Clamp values to [0,1] with Math.max(0, Math.min(1, value)) before passing them.
Use clamped interpolation for any value driving these fields.
Remember the field list: pivot (color-correction), similarity/smoothness/spillSuppression (color-key).
Omit a field to use its default rather than risk an over-1 value.

When it happens

Trigger: Reached when colorCorrection({pivot}) gets pivot > 1, or when colorKey({similarity | smoothness | spillSuppression}) gets a value > 1. Validation runs via validateUnitInterval at color-utils.ts:62 after the lower-bound check passes.

Common situations: Animated values from interpolate/Spring that overshoot above 1 without clamping, a value ported from another tool's scale, or a slider whose max exceeds 1.

Related errors

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