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

TypeError thrown by halftone-linear-gradient when colorMode is 'source' but a dotColor prop is also present. In 'source' mode the dots sample their color from the underlying video, so a separate dotColor is meaningless and would be silently ignored — the library rejects it to prevent confusion. Note the check uses 'dotColor' in params, so explicitly passing dotColor: undefined still counts as 'present'.

Source

Thrown at packages/effects/src/halftone-linear-gradient.ts:241

const validateHalftoneLinearGradientParams = (
	params: HalftoneLinearGradientParams,
): void => {
	assertEffectParamsObject(params, 'Halftone linear gradient');
	assertOptionalFiniteNumber(params.firstStopDotSize, 'firstStopDotSize');
	assertOptionalFiniteNumber(params.secondStopDotSize, 'secondStopDotSize');
	assertOptionalUvCoordinate(params.firstStopPosition, 'firstStopPosition');
	assertOptionalUvCoordinate(params.secondStopPosition, 'secondStopPosition');
	assertOptionalFiniteNumber(params.gridSize, 'gridSize');
	assertOptionalBoolean(params.maskToSourceAlpha, 'maskToSourceAlpha');
	assertOptionalEnum(
		params.colorMode,
		'colorMode',
		HALFTONE_LINEAR_GRADIENT_COLOR_MODES,
	);

	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',
	);

	if (params.firstStopDotSize !== undefined) {
		validateNonNegative(params.firstStopDotSize, 'firstStopDotSize');
	}

	if (params.secondStopDotSize !== undefined) {
		validateNonNegative(params.secondStopDotSize, 'secondStopDotSize');
	}

	if (params.gridSize !== undefined) {

View on GitHub (pinned to 78fe4bb3fd)

Solutions

1. Remove dotColor when colorMode is 'source'.
2. Conditionally include dotColor only for 'solid': {colorMode, ...(colorMode==='solid' ? {dotColor} : {})}.
3. If you need custom colors, keep colorMode as 'solid' and set dotColor.

Example fix

// before
<halftoneLinearGradient colorMode="source" dotColor="#ff00aa" />
// -> "dotColor" can only be set when "colorMode" is "solid"

// after (source mode)
<halftoneLinearGradient colorMode="source" />

// after (solid mode keeps the color)
<halftoneLinearGradient colorMode="solid" dotColor="#ff00aa" />

// Only attach dotColor when colorMode is 'solid'
const colorMode: 'solid' | 'source' = 'solid';
const props = {colorMode, ...(colorMode === 'solid' ? {dotColor: '#ff00aa'} : {})};

null

null

When it happens

Trigger: validateHalftoneLinearGradientParams (line 240) throws when params.colorMode === 'source' AND 'dotColor' is an own property of params. Triggered by: <halftoneLinearGradient colorMode="source" dotColor="#fff" />, or programmatically passing {colorMode:'source', dotColor: undefined}.

Common situations: Switching colorMode to 'source' in a shared config but forgetting to remove dotColor; conditionally spreading a dotColor prop that ends up on the object even when colorMode is 'source'; copying props from a 'solid' preset.

Related errors

• "${name}" must be ${formatEnum(variants)}
• "${name}" must be >= 0, but got ${JSON.stringify(value)}
• "${name}" must be greater than 0, but got ${JSON.stringify(v
• "${name}" must be a [number, number] tuple
• "${name}" must be greater than 0, but got ${JSON.stringify(v

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