remotion-dev/remotion · error · TypeError

"${name}" must be greater than or equal to 0, but got ${JSON

Error message

"${name}" must be greater than or equal to 0, but got ${JSON.stringify(value)}

What it means

TypeError thrown by gridlines' validateNonNegative helper (gridlines.ts:203) for parameters allowed to be zero but not negative. In Gridlines it guards lineWidth and perspective. The message identifies the field and shows the offending value.

Source

Thrown at packages/effects/src/gridlines.ts:205

	rotationX: p.rotationX ?? DEFAULT_ROTATION_X,
	rotationY: p.rotationY ?? DEFAULT_ROTATION_Y,
	perspective: p.perspective ?? DEFAULT_PERSPECTIVE,
	offsetX: p.offsetX ?? DEFAULT_OFFSET_X,
	offsetY: p.offsetY ?? DEFAULT_OFFSET_Y,
	maskToSourceAlpha: p.maskToSourceAlpha ?? DEFAULT_MASK_TO_SOURCE_ALPHA,
});

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

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

const validateGridlinesParams = (params: GridlinesParams): void => {
	assertEffectParamsObject(params, 'Gridlines');
	assertOptionalFiniteNumber(params.gridSize, 'gridSize');
	assertOptionalFiniteNumber(params.lineWidth, 'lineWidth');
	assertOptionalFiniteNumber(params.rotation, 'rotation');
	assertOptionalFiniteNumber(params.rotationX, 'rotationX');
	assertOptionalFiniteNumber(params.rotationY, 'rotationY');
	assertOptionalFiniteNumber(params.perspective, 'perspective');
	assertOptionalFiniteNumber(params.offsetX, 'offsetX');
	assertOptionalFiniteNumber(params.offsetY, 'offsetY');
	assertOptionalColor(params.lineColor, 'lineColor');
	assertOptionalColor(params.backgroundColor, 'backgroundColor');
	assertOptionalBoolean(params.maskToSourceAlpha, 'maskToSourceAlpha');

View on GitHub (pinned to 78fe4bb3fd)

Solutions

Pass lineWidth/perspective as 0 or a positive number.
Clamp animated values: Math.max(0, value).
If you meant 'no perspective', pass perspective: 0 explicitly rather than a negative.

Example fix

// before
<Gridlines lineWidth={spring.width - 10} />
// spring can dip below 10 -> negative lineWidth

// after
<Gridlines lineWidth={Math.max(0, spring.width - 10)} />

Defensive patterns

Strategy: validation

Validate before calling

const assertNonNegative = (v: number, name: string) => {
  if (!Number.isFinite(v) || v < 0) {
    throw new TypeError(`${name} must be >= 0, got ${v}`);
  }
};
assertNonNegative(params.lineWidth ?? 0, 'lineWidth');
assertNonNegative(params.perspective ?? 0, 'perspective');

Type guard

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

Try / catch

null

Prevention

Clamp animated lineWidth/perspective with Math.max(0, value).
Pass 0 explicitly to mean 'none' rather than a negative.
Watch spring/interpolation overshoot below zero.

When it happens

Trigger: validateGridlinesParams calls validateNonNegative for lineWidth (line 226) and perspective (line 227). Triggered by passing lineWidth < 0 or perspective < 0. Zero is allowed (no lines / no perspective), so only strictly negative finite values hit this.

Common situations: Negative lineWidth or perspective from a typo, an animation overshoot (e.g. spring interpolating below 0), or deriving the value from an offset/scale that can go negative.

Related errors

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