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 pixel value (0 means stripes pack solid).

Error message

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

What it means

Thrown by the Lines effect's validateNonNegative helper when a numeric parameter that must be >= 0 is given a negative value. In the shipped code this only guards the resolved gap (params.gap after applying the default of 0), so it fires when gap < 0. It is a TypeError raised during parameter validation before any WebGL work begins.

Source

Thrown at packages/effects/src/lines.ts:174

	}

	return `${variants
		.slice(0, -1)
		.map((variant) => `"${variant}"`)
		.join(', ')} or "${variants[variants.length - 1]}"`;
};

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 pixel value (0 means stripes pack solid).
Clamp any animated gap with Math.max(0, value) before passing it to lines().
Re-read the LinesParams JSDoc: gap is a transparent gap in pixels, default 0.

Example fix

// before
lines({ gap: animatedGap }) // animatedGap can be -5

// after
lines({ gap: Math.max(0, animatedGap) })

Defensive patterns

Strategy: validation

Validate before calling

const safeGap = Math.max(0, Number.isFinite(gap) ? gap : 0);
lines({ gap: safeGap });

Type guard

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

Prevention

Always clamp animated gap values to >= 0 before passing to lines().
Treat the LinesParams JSDoc as the source of truth: gap is a transparent pixel gap defaulting to 0.
Distinguish gap (>= 0) from thickness (> 0) — they use different validators.

When it happens

Trigger: Calling lines({ gap: -1 }) (or any negative number for gap) on the Lines effect. The check runs after defaults are applied, so an explicitly negative gap is the only trigger; thickness is guarded separately by validatePositive.

Common situations: Passing an animated/keyframed gap that undershoots below 0, or computing gap from an expression that can go negative. Confusing gap with thickness (which has the stricter > 0 rule).

Related errors

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