remotion-dev/remotion · error · TypeError

The bitrate quality must be one of ${VIDEO_MATTING_QUALITIES

Error message

The bitrate quality must be one of ${VIDEO_MATTING_QUALITIES.join(', ')}.

What it means

When resolveVideoMattingQuality receives a string (a quality preset), it must be one of the entries in VIDEO_MATTING_QUALITIES; anything else throws a TypeError listing the allowed values. The preset maps to a Quality with preferBitrate enabled. This keeps bitrate selection constrained to supported presets.

Source

Thrown at packages/video-matting/src/video-matting-quality.ts:27

] as const;

export type VideoMattingQuality = (typeof VIDEO_MATTING_QUALITIES)[number];

export type VideoMattingBitrate = number | VideoMattingQuality;

export const resolveVideoMattingQuality = (
	value: VideoMattingBitrate,
): Quality => {
	if (typeof value === 'number') {
		if (!Number.isInteger(value) || value <= 0) {
			throw new TypeError('A numeric bitrate must be a positive integer.');
		}

		return new Quality({bitrate: value});
	}

	if (!VIDEO_MATTING_QUALITIES.includes(value)) {
		throw new TypeError(
			`The bitrate quality must be one of ${VIDEO_MATTING_QUALITIES.join(', ')}.`,
		);
	}

	return new Quality({quality: value, preferBitrate: true});
};

View on GitHub (pinned to b2f4e34732)

Solutions

Use one of the exact allowed values listed in the error message (e.g. 'low', 'medium', 'high')
Normalize user input: value.trim().toLowerCase() and match against VIDEO_MATTING_QUALITIES before calling
Import and validate against the exported VIDEO_MATTING_QUALITIES list instead of hardcoding strings
Fall back to a default preset when the configured value is unrecognized

Example fix

// before
resolveVideoMattingQuality('High');
// after
const preset = String(input).trim().toLowerCase();
if (!VIDEO_MATTING_QUALITIES.includes(preset)) throw new Error(`Unknown preset: ${preset}`);
resolveVideoMattingQuality(preset);

Defensive patterns

Strategy: validation

Validate before calling

const isPreset = (v: unknown): v is VideoMattingQuality =>
  typeof v === 'string' && (VIDEO_MATTING_QUALITIES as readonly string[]).includes(v);
if (typeof value === 'string' && !isPreset(value)) throw new TypeError(`Unknown preset: ${value}`);

Type guard

const isQualityPreset = (v: unknown): v is QualityPreset =>
  typeof v === 'string' && (VIDEO_MATTING_QUALITIES as readonly string[]).includes(v);

Try / catch

try {
  const quality = resolveVideoMattingQuality(input);
} catch (err) {
  if (err instanceof TypeError && err.message.startsWith('The bitrate quality must be one of')) {
    console.error(`Invalid preset "${input}". Allowed: ${err.message}`);
    return resolveVideoMattingQuality('medium');
  }
  throw err;
}

Prevention

Always normalize user input with .trim().toLowerCase() before matching presets
Import VIDEO_MATTING_QUALITIES and validate against it instead of hardcoding strings
Use TypeScript union types so invalid presets fail at compile time
Don't copy quality names from other APIs without checking this package's enum

When it happens

Trigger: Passing a string that is not an exact member of VIDEO_MATTING_QUALITIES — e.g. 'high-quality', '4K', uppercase 'HIGH', or a typo like 'meduim' — through the video matting quality option.

Common situations: Config from CLI/JSON where free-text is accepted, casing mismatches after user input, or copying a quality name from a different Remotion API that uses a different enum.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

AI-assisted analysis of remotion-dev/remotion@b2f4e34732 (2026-09-09). Data as JSON: /api/errors/e9e6f36029d7f490. Report an issue: GitHub.