remotion-dev/remotion · error · TypeError

"rays" must be a finite number, but got ${JSON.stringify(ray

Error message

"rays" must be a finite number, but got ${JSON.stringify(rays)}

What it means

validateStarburstEffectParams() throws this TypeError when params.rays is missing, not a number, NaN, or Infinity (checked via typeof === 'number' && Number.isFinite). `rays` is a required field on StarburstEffectParams (it has no default), so it must be supplied as a finite integer.

Source

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

const resolve = (p: StarburstEffectParams): StarburstResolved => ({
	rays: p.rays,
	colors: p.colors,
	rotation: p.rotation ?? 0,
	smoothness: p.smoothness ?? 0,
	origin: (p.origin ?? DEFAULT_ORIGIN) as StarburstOrigin,
});

const validateStarburstEffectParams = (params: StarburstEffectParams): void => {
	if (params === null || typeof params !== 'object') {
		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(

View on GitHub (pinned to 78fe4bb3fd)

Solutions

  1. Provide a finite integer for rays, e.g. starburst({ rays: 12, colors: [...] }).
  2. If rays comes from user input, coerce and validate it (Number.parseInt then Number.isFinite) before calling starburst().
  3. Add a TypeScript type (rays: number) so the compiler flags missing or mistyped values.
  4. Double-check the value is not the result of NaN-producing arithmetic upstream.

Example fix

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

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

Strategy: validation

Validate before calling

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

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

Type guard

function isFiniteNumber(v: unknown): v is number {
  return typeof v === 'number' && Number.isFinite(v);
}

Try / catch

try {
  starburst({ rays, colors });
} catch (err) {
  if (err instanceof TypeError && /"rays" must be a finite number/.test(err.message)) {
    console.error('starburst() rays must be a finite number:', rays);
    throw err;
  }
  throw err;
}

Prevention

When it happens

Trigger: Calling starburst() with rays omitted, set to undefined, a string like '12', NaN, or Infinity; or passing a floating value that was meant for a different field. The check runs before the range check, so even a finite-but-out-of-range value passes this guard and fails at error 915 instead.

Common situations: Forgetting the required `rays` field; reading rays from an input that yields undefined; passing a string from a form field without coercion; math that produced NaN (e.g. dividing by zero) feeding into rays.

Related errors

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