remotion-dev/remotion · error · TypeError

${name} params must be an object

Error message

${name} params must be an object

What it means

`assertParamsObject` runs at the top of `validateMetallicSwirlParams` and rejects a params value that is not a plain object: `null`, an array, a primitive (string/number/boolean), or `typeof !== 'object'`. Because `MetallicSwirlParams` declares all keys optional, callers sometimes pass a non-object that still satisfies loose typing; this guard stops it before any key is read.

Source

Thrown at packages/brand/src/effects/metallic-swirl-effect.ts:268

	colorPhaseR: params.colorPhaseR ?? DEFAULT_COLOR_PHASE,
	colorPhaseG: params.colorPhaseG ?? DEFAULT_COLOR_PHASE,
	colorPhaseB: params.colorPhaseB ?? DEFAULT_COLOR_PHASE,
	colorRange: params.colorRange ?? DEFAULT_COLOR_RANGE,
	colorBias: params.colorBias ?? DEFAULT_COLOR_BIAS,
	colorA: params.colorA ?? DEFAULT_COLOR_A,
	colorB: params.colorB ?? DEFAULT_COLOR_B,
	brightness: params.brightness ?? DEFAULT_BRIGHTNESS,
	backgroundColor: params.backgroundColor ?? DEFAULT_BACKGROUND_COLOR,
	opacity: params.opacity ?? DEFAULT_OPACITY,
	mode: params.mode ?? DEFAULT_MODE,
});

const assertParamsObject = (
	params: MetallicSwirlParams,
	name: string,
): void => {
	if (params === null || typeof params !== 'object' || Array.isArray(params)) {
		throw new TypeError(`${name} params must be an object`);
	}
};

const assertOptionalFiniteNumber = (
	value: unknown,
	name: keyof MetallicSwirlParams,
): void => {
	if (value === undefined) {
		return;
	}

	if (typeof value !== 'number' || !Number.isFinite(value)) {
		throw new TypeError(`"${name}" must be a finite number`);
	}
};

const validateRange = (
	value: number,

View on GitHub (pinned to 78fe4bb3fd)

Solutions

1. Pass a plain object: `metallicSwirl({})` or `metallicSwirl({speed: 2})`.
2. If the value comes from JSON, call `JSON.parse` first and ensure the result is a non-array object.
3. Coerce at the boundary: `const p = (v && typeof v === 'object' && !Array.isArray(v)) ? v : {};`.
4. Type the params variable as `MetallicSwirlParams` so TypeScript flags non-objects.

Example fix

// before
const e = metallicSwirl(rawConfig); // rawConfig is a JSON string

// after
const parsed = JSON.parse(rawConfig);
const e = metallicSwirl(parsed);

// Ensure params is a plain object before passing to metallicSwirl.
const asParamsObject = (v: unknown): Record<string, unknown> => {
  if (v === null || typeof v !== 'object' || Array.isArray(v)) {
    return {}; // or throw, depending on desired strictness
  }
  return v as Record<string, unknown>;
};
metallicSwirl(asParamsObject(rawConfig));

const isPlainObject = (v: unknown): v is Record<string, unknown> =>
  v !== null && typeof v === 'object' && !Array.isArray(v);

When it happens

Trigger: Calling `metallicSwirl(null)`, `metallicSwirl(undefined)` is fine (defaulted to `{}`), but `metallicSwirl(null)` is not; `metallicSwirl([])`, `metallicSwirl('blend')`, `metallicSwirl(5)`, or passing a serialized JSON string instead of a parsed object.

Common situations: Forwarding a deserialized value that was not parsed (`JSON.parse` skipped); passing a single default name as a string; spreading an array into the effect; receiving params from an untyped boundary (postMessage, URL query).

Related errors

• "${name}" must be a finite number
• "${name}" must be between ${min} and ${max}
• "${name}" must be one of ${variants.join(', ')}
• "backgroundColor" must be a string
• "colorA" must be a string

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