remotion-dev/remotion · error · TypeError

"colors" must be an array with at least 2 colors, but got ${

Error message

"colors" must be an array with at least 2 colors, but got ${JSON.stringify(colors)}

What it means

Thrown by validateColors() during checkerboard validation when the colors prop is defined but is not an array of at least 2 entries. The checkerboard needs >= 2 colors to cycle through cells, so anything fewer is rejected as a TypeError before rendering. Each entry is then additionally validated as a color.

Source

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

		);
	}
};

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}]`);
	}
};

const validateCheckerboardParams = (params: CheckerboardParams): void => {
	assertEffectParamsObject(params, 'Checkerboard');
	validateColors(params.colors);
	assertOptionalFiniteNumber(params.cellSize, 'cellSize');
	assertOptionalFiniteNumber(params.gap, 'gap');
	assertOptionalFiniteNumber(params.angle, 'angle');
	assertOptionalFiniteNumber(params.offsetX, 'offsetX');
	assertOptionalFiniteNumber(params.offsetY, 'offsetY');
	assertOptionalBoolean(params.maskToSourceAlpha, 'maskToSourceAlpha');

View on GitHub (pinned to 78fe4bb3fd)

Solutions

Provide at least two color strings: colors={['#dff4ff', '#7cc6ff']}.
If omitted entirely, the default two colors are used — simply remove the prop.
Coerce a delimited string to an array before passing: 'a,b'.split(',').
Validate dynamic data length before rendering and fall back to the default when fewer than 2 entries exist.

Example fix

// before
<Checkerboard colors={['#fff']} />

// after
<Checkerboard colors={['#dff4ff', '#7cc6ff']} />

Defensive patterns

Strategy: type-guard

Validate before calling

const colors = rawColors ?? ['#dff4ff', '#7cc6ff'];
if (!Array.isArray(colors) || colors.length < 2) {
  throw new Error('Checkerboard colors must be an array with at least 2 entries');
}
// then: <Checkerboard colors={colors as readonly string[]} />

Type guard

const isColorArray = (v: unknown): v is readonly string[] =>
  Array.isArray(v) && v.length >= 2 && v.every((c) => typeof c === 'string');

Prevention

Pass an array literal, never a comma-separated string.
For dynamic palettes, fall back to the default when fewer than 2 entries are available.
Use isColorArray to narrow external data before handing it to the effect.

When it happens

Trigger: Passing <Checkerboard colors={['#fff']} /> (single color), colors={null}, colors={'#fff,#000'} (a string instead of array), or colors={[]} (empty); validateColors() throws at checkerboard.ts:168.

Common situations: Passing a comma-separated string instead of an array, a data source returning one item, spreading an empty array, or forgetting the default and providing a single-element array.

Related errors

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