remotion-dev/remotion · error · TypeError

"${name}" must be one of ${variants.join(', ')}

Error message

"${name}" must be one of ${variants.join(', ')}

What it means

`assertOptionalEnum` checks the `mode` field against `MODES = ['blend', 'alpha-mask']`. `undefined` is allowed (defaults to 'blend'), but any non-string or any string not in the variants throws. The message lists the valid variants.

Source

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

	min: number,
	max: number,
): void => {
	if (value < min || value > max) {
		throw new TypeError(`"${name}" must be between ${min} and ${max}`);
	}
};

const assertOptionalEnum = <T extends string>(
	value: unknown,
	name: keyof MetallicSwirlParams,
	variants: readonly T[],
): void => {
	if (value === undefined) {
		return;
	}

	if (typeof value !== 'string' || !variants.includes(value as T)) {
		throw new TypeError(`"${name}" must be one of ${variants.join(', ')}`);
	}
};

const parseHexColor = (hex: string, name: keyof MetallicSwirlParams): Rgb => {
	const match = /^#?([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})$/i.exec(hex);
	if (!match) {
		throw new TypeError(`"${name}" must be a hex color such as "#000000"`);
	}

	return [
		parseInt(match[1], 16) / 255,
		parseInt(match[2], 16) / 255,
		parseInt(match[3], 16) / 255,
	];
};

const validateMetallicSwirlParams = (
	params: MetallicSwirlParams = {},

View on GitHub (pinned to 78fe4bb3fd)

Solutions

1. Use exactly one of the listed variants: `'blend'` or `'alpha-mask'`.
2. Normalize user input to lowercase and validate against the list before passing.
3. Omit `mode` entirely if you want the default (`'blend'`).
4. Type the field as `MetallicSwirlMode` so invalid literals are rejected at compile time.

Example fix

// before
metallicSwirl({mode: 'BLEND'}); // wrong case

// after
metallicSwirl({mode: 'blend'});

// Validate the mode enum before passing.
const MODES = ['blend', 'alpha-mask'] as const;
type MetallicSwirlMode = (typeof MODES)[number];

const asMode = (v: unknown): MetallicSwirlMode | undefined => {
  if (v === undefined) return undefined;
  if (typeof v === 'string' && (MODES as readonly string[]).includes(v)) {
    return v as MetallicSwirlMode;
  }
  throw new Error(`mode must be one of ${MODES.join(', ')}`);
};
metallicSwirl({mode: asMode(raw.mode)});

const isMetallicSwirlMode = (v: unknown): v is MetallicSwirlMode =>
  typeof v === 'string' && (MODES as readonly string[]).includes(v);

When it happens

Trigger: `metallicSwirl({mode: 'normal'})`, `metallicSwirl({mode: 'BLEND'})` (case-sensitive), `metallicSwirl({mode: 1})` (number), `metallicSwirl({mode: null})`.

Common situations: Typo in a config file; case mismatch from user input; passing a numeric index instead of the string name; copy-paste from a different effect's mode names.

Related errors

• ${name} params must be an object
• "${name}" must be a finite number
• "${name}" must be between ${min} and ${max}
• "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/9592f51d9ff1fa9a. Report an issue: GitHub.