remotion-dev/remotion · error · TypeError

Starburst effect requires a parameters object, but got ${JSO

Error message

Starburst effect requires a parameters object, but got ${JSON.stringify(params)}

What it means

validateStarburstEffectParams() in packages/effects/src/starburst.ts throws this TypeError when the params passed to starburst() are not an object — i.e. null, undefined, or a primitive. starburst() requires a parameters object with at least `rays` and `colors`, so rejecting non-objects up front prevents a confusing downstream crash inside resolve() or the WebGL setup.

Source

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

type StarburstResolved = {
	rays: number;
	colors: readonly string[];
	rotation: number;
	smoothness: number;
	origin: StarburstOrigin;
};

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(

View on GitHub (pinned to 78fe4bb3fd)

Solutions

Pass a parameters object literal with the required `rays` and `colors` fields: starburst({ rays: 12, colors: ['#ff0000','#00ff00'] }).
If the value comes from JSON or an untyped source, narrow it with a type guard before calling starburst().
Audit the call site for accidental undefined/null (e.g. a destructuring that produced undefined).
Add a TypeScript type annotation on the variable so the compiler rejects non-object inputs at build time.

Example fix

// before
const params = JSON.parse(configText);
starburst(params); // params may be null/primitive

// after
const params = JSON.parse(configText);
if (typeof params !== 'object' || params === null) {
  throw new Error('starburst config must be an object');
}
starburst({ rays: params.rays, colors: params.colors });

Defensive patterns

Strategy: type-guard

Validate before calling

function isStarburstParamsObject(v: unknown): v is Record<string, unknown> {
  return typeof v === 'object' && v !== null;
}

const raw: unknown = JSON.parse(configText);
if (!isStarburstParamsObject(raw)) {
  throw new Error('starburst() requires a parameters object');
}
starburst({ rays: raw.rays, colors: raw.colors });

Type guard

function isStarburstParams(v: unknown): v is { rays: unknown; colors: unknown } {
  return typeof v === 'object' && v !== null && 'rays' in v && 'colors' in v;
}

Try / catch

try {
  starburst(maybeParams as StarburstEffectParams);
} catch (err) {
  if (err instanceof TypeError && /Starburst effect requires a parameters object/.test(err.message)) {
    console.error('starburst() was called without a params object:', maybeParams);
    // fix the source of the value, then retry
    throw err;
  }
  throw err;
}

Prevention

Always call starburst() with an object literal: starburst({ rays, colors }).
Type untrusted inputs (JSON, config) before passing them to starburst().
Let TypeScript's StarburstEffectParams type flag missing arguments at build time.
Validate at the trust boundary when deserializing effect parameters.

When it happens

Trigger: Calling starburst(null), starburst(undefined), or starburst('starburst') — typically from untyped JavaScript, deserialized JSON, or a refactor that removed the argument. In TypeScript this is suppressed at compile time by the StarburstEffectParams type, so it surfaces mainly in JS callers or escaped `any` values.

Common situations: Passing a value loaded from JSON/config without validation; a partial refactor that left starburst() with no argument; spreading a possibly-null variable; calling the effect from dynamically-built effect arrays.

Related errors

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