remotion-dev/remotion · error · Error

Unsupported video matting model "${model}". Available models

Error message

Unsupported video matting model "${model}". Available models: ${VIDEO_MATTING_MODELS.join(', ')}.

What it means

getVideoMattingModelInfo is a lookup guard: when asked for a model key not present in the MODEL_INFO registry, it throws listing the supported models from VIDEO_MATTING_MODELS. Callers pass an invalid VideoMattingModel string, often a typo or a model name not shipped in the installed package version.

Source

Thrown at packages/video-matting/src/models.ts:60

};

export const getAvailableModels = (): VideoMattingModelInfo[] => {
	return VIDEO_MATTING_MODELS.map((model) => {
		const {
			revision: _revision,
			dtype: _dtype,
			requiresShaderF16: _requiresShaderF16,
			...info
		} = MODEL_INFO[model];
		return {...info};
	});
};

export const getVideoMattingModelInfo = (
	model: VideoMattingModel,
): InternalVideoMattingModelInfo => {
	if (!Object.hasOwn(MODEL_INFO, model)) {
		throw new Error(
			`Unsupported video matting model "${model}". Available models: ${VIDEO_MATTING_MODELS.join(', ')}.`,
		);
	}

	return MODEL_INFO[model];
};

export const getHostedVideoMattingModelId = (
	model: VideoMattingModel,
): string => {
	return HOSTED_MODEL_IDS[model];
};

View on GitHub (pinned to b2f4e34732)

Solutions

Pick a model from the list printed in the error message
Update to a currently supported model id if yours was removed in an upgrade
Validate user/config-supplied model names against VIDEO_MATTING_MODELS before calling

Example fix

// before
const model = 'modnet-large' as VideoMattingModel;
// after
const model: VideoMattingModel = 'Xenova/modnet';

Defensive patterns

Strategy: type-guard

Validate before calling

if (!(VIDEO_MATTING_MODELS as readonly string[]).includes(model)) {
  model = 'Xenova/modnet'; // default
}

Type guard

const isVideoMattingModel = (m: string): m is VideoMattingModel =>
  (VIDEO_MATTING_MODELS as readonly string[]).includes(m);

Try / catch

try {
  const info = getVideoMattingModelInfo(model);
} catch (e) {
  if ((e as Error).message.startsWith('Unsupported video matting model')) {
    // use default model
  }
  throw e;
}

Prevention

Type user input as VideoMattingModel at the boundary
Validate model names coming from config/CLI against the union
Re-check model ids after upgrading Remotion

When it happens

Trigger: Calling getVideoMattingModelInfo('my-model') or passing model to matting APIs with a value outside the VIDEO_MATTING_MODELS union (often a string that bypassed TypeScript typing via `as` or plain JS).

Common situations: Typo in model name; upgrading Remotion added/renamed models while old code uses a removed id; stringly-typed config from a database or CLI where the union type is not enforced.

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/bea81901fd285312. Report an issue: GitHub.