remotion-dev/remotion · error · TypeError

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

Q: What causes ""${name}" must be greater than or equal to 0, but got ${JSON.stringify(value)}" in remotion-dev/remotion?

Set gap to 0 or a positive number of pixels.

Error message

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

What it means

Thrown by validateNonNegative() during checkerboard validation when a numeric prop that may be zero but not negative is < 0. In the shipped validator this is applied to gap (transparent spacing between cells). It is a TypeError raised during parameter validation, before any GL setup.

Source

Thrown at packages/effects/src/checkerboard.ts:156

		spacing: cellSize + gap,
		angle: p.angle ?? DEFAULT_ANGLE,
		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 validateColors = (colors: unknown): void => {
	if (colors === undefined) {
		return;
	}

	if (!Array.isArray(colors) || colors.length < 2) {
		throw new TypeError(
			`"colors" must be an array with at least 2 colors, but got ${JSON.stringify(colors)}`,
		);
	}

	for (let i = 0; i < colors.length; i++) {
		assertRequiredColor(colors[i], `colors[${i}]`);

View on GitHub (pinned to 78fe4bb3fd)

Solutions

Set gap to 0 or a positive number of pixels.
Clamp animated gap with Math.max(0, value).
Re-check keyframes that interpolate below 0.

Example fix

// before
<Checkerboard gap={-4} />

// after
<Checkerboard gap={0} />

// animated, clamped
<Checkerboard gap={Math.max(0, interpolate(frame, [0, 30], [10, -2]))} />

Defensive patterns

Strategy: validation

Validate before calling

const gap = Number(rawGap);
if (!(Number.isFinite(gap) && gap >= 0)) {
  throw new Error(`gap must be >= 0, got ${rawGap}`);
}
// then: <Checkerboard gap={gap} />

Type guard

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

Prevention

Clamp animated gap with Math.max(0, value).
Remember gap is the only checkerboard numeric allowed to be 0; cellSize is not.
Guard externally sourced gap values with isNonNegativeNumber before render.

When it happens

Trigger: Passing <Checkerboard gap={-1} /> or a keyframed gap that dips below 0; validateCheckerboardParams() calls validateNonNegative(gap,'gap') which throws at checkerboard.ts:156 because value < 0.

Common situations: Negative gap from a dynamic data source, animation overshoot below zero, or assuming gap can be negative to overlap cells (it cannot).

Related errors

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