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

Pass an actual boolean: lines({colors: [...], maskToSourceAlpha: true})

remotion-dev/remotion · error · TypeError

"${name}" must be a boolean, but got ${JSON.stringify(value)

Error message

"${name}" must be a boolean, but got ${JSON.stringify(value)}

What it means

Thrown by assertOptionalBoolean when a parameter is provided (not undefined) but is not a boolean. This validator is used by effects with optional boolean toggles: lines, waves, checkerboard, contour-lines, gridlines, and halftone-linear-gradient (typically for maskToSourceAlpha). Undefined is allowed and skips validation; any other non-boolean type triggers the error.

Source

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

		);
	}
};

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;
	}

	if (typeof value !== 'boolean') {
		throw new TypeError(
			`"${name}" must be a boolean, but got ${JSON.stringify(value)}`,
		);
	}
};

View on GitHub (pinned to 78fe4bb3fd)

Solutions

Pass an actual boolean: lines({colors: [...], maskToSourceAlpha: true})
If omitting the toggle, remove the field or set to undefined — not null or 0
Coerce config values: Boolean(value) if you know the source uses 0/1 or strings
Filter out null before passing: const params = raw.maskToSourceAlpha == null ? {} : {maskToSourceAlpha: Boolean(raw.maskToSourceAlpha)}

Example fix

// before
const e = lines({colors: ['#fff'], maskToSourceAlpha: 1});

// after
const e = lines({colors: ['#fff'], maskToSourceAlpha: true});

Defensive patterns

Strategy: validation

Validate before calling

function isOptionalBoolean(value: unknown): boolean {
  return value === undefined || typeof value === 'boolean';
}

// Before calling:
if (!isOptionalBoolean(params.maskToSourceAlpha)) {
  throw new Error('maskToSourceAlpha must be a boolean or omitted');
}
const e = lines(params);

Type guard

function isOptionalBoolean(value: unknown): value is boolean | undefined {
  return value === undefined || typeof value === 'boolean';
}

Prevention

Pass actual booleans (true/false), never 0/1 or 'true'/'false' strings
Omit optional boolean fields entirely if you do not need to set them — do not pass null
Coerce 0/1 or string values with Boolean() before passing to effects
Filter null from external data: use undefined in its place for optional fields

When it happens

Trigger: Passing maskToSourceAlpha: 1 instead of maskToSourceAlpha: true; passing maskToSourceAlpha: 'yes'; passing maskToSourceAlpha: null (null is not undefined, so it fails the typeof boolean check).

Common situations: Config or API data uses 0/1 or 'true'/'false' strings instead of actual booleans; JSON from an external source where the field is null rather than omitted; developer assumes truthy values are accepted.

Related errors

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