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

validateStarburstEffectParams() throws this TypeError when params.colors is not an array or has fewer than 2 entries. The starburst pattern alternates between colors around the circle, so at least two are mandatory; a single color or a non-array cannot produce the effect and the GLSL palette sampler would be degenerate.

Source

Thrown at packages/effects/src/starburst.ts:110

		throw new TypeError(
			`Starburst effect requires a parameters object, but got ${JSON.stringify(params)}`,
		);
	}

	const {rays, colors} = params;

	if (typeof rays !== 'number' || !Number.isFinite(rays)) {
		throw new TypeError(
			`"rays" must be a finite number, but got ${JSON.stringify(rays)}`,
		);
	}

	if (rays < 2 || rays > 100) {
		throw new RangeError(`"rays" must be between 2 and 100, but got ${rays}`);
	}

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

	const r = resolve(params);

	if (typeof r.rotation !== 'number' || !Number.isFinite(r.rotation)) {
		throw new TypeError(
			`"rotation" must be a finite number, but got ${JSON.stringify(params.rotation)}`,
		);
	}

	if (typeof r.smoothness !== 'number' || !Number.isFinite(r.smoothness)) {
		throw new TypeError(
			`"smoothness" must be a finite number, but got ${JSON.stringify(params.smoothness)}`,
		);
	}

View on GitHub (pinned to 78fe4bb3fd)

Solutions

Pass an array of at least two color strings: starburst({ rays: 12, colors: ['#ff0000', '#00ff00'] }).
If colors come from dynamic input, guard with Array.isArray(c) && c.length >= 2 before calling starburst().
Provide a fallback palette of >= 2 colors when the source is empty.
Add a TypeScript type (colors: readonly string[]) so the compiler flags non-array or short arrays at build time.

Example fix

// before
starburst({ rays: 12, colors: '#ff0000' });
starburst({ rays: 12, colors: ['#ff0000'] });

// after
starburst({ rays: 12, colors: ['#ff0000', '#00ff00'] });

Defensive patterns

Strategy: type-guard

Validate before calling

function assertColors(v: unknown): readonly string[] {
  if (!Array.isArray(v) || v.length < 2) {
    throw new TypeError('"colors" must be an array with at least 2 colors');
  }
  return v as readonly string[];
}

starburst({ rays, colors: assertColors(input.colors) });

Type guard

function isColorsArray(v: unknown): v is readonly string[] {
  return Array.isArray(v) && v.length >= 2 && v.every((c) => typeof c === 'string');
}

Try / catch

try {
  starburst({ rays, colors });
} catch (err) {
  if (err instanceof TypeError && /"colors" must be an array with at least 2 colors/.test(err.message)) {
    console.error('starburst() needs an array of >= 2 color strings:', colors);
    throw err;
  }
  throw err;
}

Prevention

Always pass colors as an array of at least two strings.
Type and guard colors from untrusted sources before calling starburst().
Provide a fallback palette when the source might be empty.
Use the StarburstEffectParams type so the compiler flags short/non-array values.

When it happens

Trigger: Calling starburst() with colors omitted, set to a single color string instead of an array (e.g. '#ff0000'), an array of length 0 or 1, or a non-array value like an object. The check is Array.isArray(colors) && colors.length >= 2.

Common situations: Passing a bare string where an array is expected; forgetting to wrap the second color; reading colors from config that yielded undefined; spreading a possibly-empty array; a refactor that dropped the array wrapper.

Related errors

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