What causes ""${name}" must be a non-empty string, but got ${JSON.stringify(value)}" in remotion-dev/remotion?

Pass a valid CSS color string: tint({color: '#ff0000'}) or tint({color: 'red'})

remotion-dev/remotion · error · TypeError

"${name}" must be a non-empty string, but got ${JSON.stringi

Error message

"${name}" must be a non-empty string, but got ${JSON.stringify(value)}

What it means

Thrown by assertRequiredColor when a color parameter is not a string or is an empty string. This validator backs the required color params of effects like tint (color), lines/waves/checkerboard (colors[i] in a loop). The empty-string check catches the common mistake of passing '' as a default. assertOptionalColor delegates here for non-undefined values, so effects like vignette, drop-shadow, gridlines, contour-lines, and halftone-linear-gradient also trigger this for their optional color fields.

Source

Thrown at packages/effects/src/validate-effect-param.ts:25

			`${effectLabel} effect requires a parameters object, but got ${JSON.stringify(params)}`,
		);
	}
};

export const assertRequiredFiniteNumber = (
	value: unknown,
	name: string,
): void => {
	if (typeof value !== 'number' || !Number.isFinite(value)) {
		throw new TypeError(
			`"${name}" must be a finite number, but got ${JSON.stringify(value)}`,
		);
	}
};

export const assertRequiredColor = (value: unknown, name: string): void => {
	if (typeof value !== 'string' || value.length === 0) {
		throw new TypeError(
			`"${name}" must be a non-empty string, but got ${JSON.stringify(value)}`,
		);
	}
};

export const assertOptionalColor = (value: unknown, name: string): void => {
	if (value === undefined) {
		return;
	}

	assertRequiredColor(value, name);
};

export const assertOptionalBoolean = (value: unknown, name: string): void => {
	if (value === undefined) {
		return;
	}

View on GitHub (pinned to 78fe4bb3fd)

Solutions

Pass a valid CSS color string: tint({color: '#ff0000'}) or tint({color: 'red'})
If the color may be absent, omit the field entirely (set to undefined, not '') so optional validators skip it
Validate color strings before passing: ensure typeof color === 'string' && color.length > 0
Convert numeric hex to string: '#' + value.toString(16).padStart(6, '0')

Example fix

// before
const e = tint({color: ''});

// after
const e = tint({color: '#ff0000'});

Defensive patterns

Strategy: validation

Validate before calling

function isValidColor(value: unknown): boolean {
  return typeof value === 'string' && value.length > 0;
}

// Before calling:
if (!isValidColor(params.color)) {
  throw new Error('color must be a non-empty CSS color string');
}
const e = tint({color: params.color});

Type guard

function isNonEmptyString(value: unknown): value is string {
  return typeof value === 'string' && value.length > 0;
}

Prevention

Pass CSS color strings like '#ff0000' or 'rgb(255,0,0)' — never numbers or empty strings
For optional color fields, omit the key (set to undefined) rather than passing ''
Validate color strings from external/CMS data before passing to effects
Convert numeric hex to string format: '#' + num.toString(16).padStart(6, '0')

When it happens

Trigger: Calling tint({color: ''}), tint({color: null}), tint({color: '#ff0'}), or passing a non-string (number, object) as a color. Also triggered via assertOptionalColor when an optional color field is set to '' or a non-string — e.g. vignette({color: 0}).

Common situations: Color value comes from a config file or CMS where it was left blank; developer passes a hex number (0xff0000) instead of a hex string ('#ff0000'); optional color field defaults to '' instead of undefined; data deserialized from JSON where the field is null.

Related errors

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