remotion-dev/remotion · error · Error

The video matting model "${model}" returned ${result.channel

Error message

The video matting model "${model}" returned ${result.channels} channels instead of RGBA.

What it means

The loaded transformers.js matting pipeline produced a tensor whose channel count is not 4 (RGBA). Video matting models must return alpha-augmented RGBA frames for compositing; anything else indicates the chosen model is not a matting model or its output format changed.

Source

Thrown at packages/video-matting/src/load-video-matting-model.ts:243

						task: 'background-removal',
						model: transformerModel,
						processor: transformerProcessor,
					}) as unknown as TransformerPipeline;
					const loadedTransformerPipeline = transformerPipeline;

					notifyProgress(state, {
						status: 'ready',
						file: null,
						progress: 1,
						loadedBytes: totalBytes,
						totalBytes,
					});

					const loadedPipeline: LoadedPipeline = {
						run: async (image) => {
							const result = await loadedTransformerPipeline(image);
							if (result.channels !== 4) {
								throw new Error(
									`The video matting model "${model}" returned ${result.channels} channels instead of RGBA.`,
								);
							}

							const data =
								result.data instanceof Uint8ClampedArray &&
								result.data.buffer instanceof ArrayBuffer
									? (result.data as Uint8ClampedArray<ArrayBuffer>)
									: new Uint8ClampedArray(result.data);

							return {
								data,
								width: result.width,
								height: result.height,
								channels: 4,
							};
						},
						dispose: () => loadedTransformerPipeline.dispose(),

View on GitHub (pinned to b2f4e34732)

Solutions

1. Use one of the supported VIDEO_MATTING_MODELS (see models.ts) instead of a custom model id
2. If using a custom model, verify it outputs 4-channel RGBA (e.g. modify the post-processing to emit an alpha channel)
3. Pin the model revision that matches the tested output format

Example fix

// before
const model = 'Xenova/depth-anything-small';
// after
const model = 'Xenova/modnet'; // a matting model returning RGBA

import {VIDEO_MATTING_MODELS} from '@remotion/video-matting';
if (!VIDEO_MATTING_MODELS.includes(model)) {
  throw new Error(`Unsupported matting model: ${model}`);
}

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

try {
  await runPipeline(image);
} catch (e) {
  if ((e as Error).message.includes('channels instead of RGBA')) {
    // fall back to a default supported matting model
  }
  throw e;
}

When it happens

Trigger: Passing a model id (e.g. a segmentation or classification model) to loadVideoMattingModel / getOrCreateVideoMattingPipeline whose inference result has 1 or 3 channels.

Common situations: Typo or custom model id in the model option; a Hugging Face model swapped for a new revision with different output; using a non-RGBA model like a depth estimator with the matting API.

Understand the failure class

Background: Tensor shape mismatch errors ("must have shape", "expected shape ... got ..."): when tensor dimensions disagree with what an op or layer was told to expect — this error's family across 6 libraries.

Related errors

• Invalid channel configuration ${channelConfiguration}
• Unsupported video matting model "${model}". Available models

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