remotion-dev/remotion · error · TypeError

"${name}" must be ${formatEnum(variants)}

Error message

"${name}" must be ${formatEnum(variants)}

What it means

Thrown by assertOptionalEnum() in the halftone effect's validateParams when one of the enum-typed parameters — shape, sampling, or colorMode — is present but not one of the allowed variants. Each parameter has its own allowed list (shape: 'circle'|'square'|'line'; sampling: 'bilinear'|'nearest'; colorMode: 'solid'|'source'), and the message uses formatEnum() to list them, so the actual text names which value was wrong by parameter name.

Source

Thrown at packages/effects/src/halftone.ts:160

	}

	return `${variants
		.slice(0, -1)
		.map((variant) => `"${variant}"`)
		.join(', ')} or "${variants[variants.length - 1]}"`;
};

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

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

const resolve = (p: HalftoneParams): HalftoneResolved => ({
	shape: p.shape ?? 'circle',
	dotSize: p.dotSize ?? 20,
	dotSpacing: p.dotSpacing ?? p.dotSize ?? 20,
	rotation: p.rotation ?? 0,
	offsetX: p.offsetX ?? 0,
	offsetY: p.offsetY ?? 0,
	sampling: p.sampling ?? 'bilinear',
	colorMode: p.colorMode ?? 'solid',
	dotColor: 'dotColor' in p ? (p.dotColor ?? 'red') : 'red',
	invert: p.invert ?? false,
});

const validateHalftoneParams = (params: HalftoneParams): void => {
	assertEffectParamsObject(params, 'Halftone');

View on GitHub (pinned to 78fe4bb3fd)

Solutions

  1. Read the parameter name in the message and set it to one of the listed variants.
  2. If you are typing values, import HalftoneShape / HalftoneSampling / HalftoneColorMode and let TypeScript narrow the literal union for you.
  3. If params come from dynamic input, validate against the allowed list before calling halftone().

Example fix

// before
halftone({ shape: 'circle', colorMode: 'grayscale' })

// after
halftone({ shape: 'circle', colorMode: 'source' })
Defensive patterns

Strategy: type-guard

Validate before calling

import type { HalftoneShape, HalftoneSampling, HalftoneColorMode } from '@remotion/effects';

const SHAPES = ['circle', 'square', 'line'] as const;
const SAMPLING = ['bilinear', 'nearest'] as const;
const COLOR_MODES = ['solid', 'source'] as const;

function isHalftoneEnum(value: unknown, allowed: readonly string[]): value is string {
  return typeof value === 'string' && (allowed as readonly string[]).includes(value);
}

// before calling halftone():
if (params.shape !== undefined && !isHalftoneEnum(params.shape, SHAPES)) {
  throw new Error(`shape must be one of ${SHAPES.join(', ')}`);
}

Type guard

function isHalftoneShape(v: unknown): v is HalftoneShape {
  return v === 'circle' || v === 'square' || v === 'line';
}
function isHalftoneSampling(v: unknown): v is HalftoneSampling {
  return v === 'bilinear' || v === 'nearest';
}
function isHalftoneColorMode(v: unknown): v is HalftoneColorMode {
  return v === 'solid' || v === 'source';
}

Prevention

When it happens

Trigger: Passing halftone({ shape: 'triangle' }), halftone({ sampling: 'cubic' }), or halftone({ colorMode: 'gradient' }). Also firing it by passing a non-string (a number, object, or null) to any of these three fields.

Common situations: Typos in the enum value; copying example code from an outdated tutorial that used a different spelling; passing the wrong variable (e.g. a color string into shape); dynamically building params from user input without validation.

Related errors

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