remotion-dev/remotion · error · TypeError

"dotColor" can only be set when "colorMode" is "solid"

Error message

"dotColor" can only be set when "colorMode" is "solid"

What it means

Thrown by validateHalftoneParams() when params.colorMode === 'source' AND a 'dotColor' key is present on the params object. In source color mode the dots take their color from the underlying frame, so a solid dotColor is contradictory; the library forbids the combination explicitly rather than silently dropping the value. Note the check is on key presence ('dotColor' in params), so even dotColor: undefined is allowed — only an explicitly-set dotColor trips it.

Source

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

	invert: p.invert ?? false,
});

const validateHalftoneParams = (params: HalftoneParams): void => {
	assertEffectParamsObject(params, 'Halftone');
	assertOptionalFiniteNumber(params.dotSize, 'dotSize');
	assertOptionalFiniteNumber(params.dotSpacing, 'dotSpacing');
	assertOptionalFiniteNumber(params.rotation, 'rotation');
	assertOptionalFiniteNumber(params.offsetX, 'offsetX');
	assertOptionalFiniteNumber(params.offsetY, 'offsetY');
	assertOptionalEnum(params.shape, 'shape', HALFTONE_SHAPES);
	assertOptionalEnum(params.sampling, 'sampling', HALFTONE_SAMPLING);
	assertOptionalEnum(params.colorMode, 'colorMode', HALFTONE_COLOR_MODES);
	if ('color' in params && params.color !== undefined) {
		throw new TypeError('"color" has been renamed to "dotColor"');
	}

	if (params.colorMode === 'source' && 'dotColor' in params) {
		throw new TypeError(
			'"dotColor" can only be set when "colorMode" is "solid"',
		);
	}

	assertOptionalColor(
		'dotColor' in params ? params.dotColor : undefined,
		'dotColor',
	);
	assertOptionalBoolean(params.invert, 'invert');

	if (params.dotSize !== undefined && params.dotSize < 1) {
		throw new TypeError(
			`"dotSize" must be >= 1, but got ${JSON.stringify(params.dotSize)}`,
		);
	}

	if (params.dotSpacing !== undefined && params.dotSpacing < 1) {
		throw new TypeError(

View on GitHub (pinned to 78fe4bb3fd)

Solutions

1. When colorMode is 'source', omit dotColor entirely from the params object.
2. Build the params object conditionally: only add dotColor when colorMode is 'solid' (or undefined).
3. If you need both code paths, branch on colorMode before constructing params.

Example fix

// before
halftone({ colorMode: 'source', dotColor: 'red' })

// after
const params = { colorMode: mode };
if (mode === 'solid') params.dotColor = 'red';
halftone(params)

// Build params conditionally so dotColor is only present in solid mode.
function buildHalftoneParams(colorMode: 'solid' | 'source', dotColor?: string) {
  const params: Record<string, unknown> = { colorMode };
  if (colorMode === 'solid' && dotColor !== undefined) params.dotColor = dotColor;
  return params;
}

// Detect the conflicting combination before calling halftone().
function isConflictingHalftoneCombo(p: unknown): boolean {
  return typeof p === 'object' && p !== null
    && (p as { colorMode?: unknown }).colorMode === 'source'
    && 'dotColor' in p;
}

When it happens

Trigger: Calling halftone({ colorMode: 'source', dotColor: 'red' }) or destructuring a params object that always includes dotColor and then switching colorMode to 'source'.

Common situations: Toggling colorMode dynamically (e.g. from Studio Visual Mode or a control panel) while leaving dotColor set; sharing one params object across modes; conditional spreads that always include dotColor.

Related errors

• "${name}" must be ${formatEnum(variants)}
• "dotSize" must be >= 1, but got ${JSON.stringify(params.dotS
• "dotSpacing" must be >= 1, but got ${JSON.stringify(params.d
• ${name} params must be an object
• "${name}" must be a finite number

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