remotion-dev/remotion · error · ProResDecoderNotEnabledError

Cannot decode "${src}": it is encoded with Apple ProRes, whi

Error message

Cannot decode "${src}": it is encoded with Apple ProRes, which WebCodecs does not support natively. ProRes decoding is not enabled by default. Register the ProRes decoder by calling registerProresDecoder() from "@mediabunny/prores" in your entry point, before registerRoot(). See https://www.remotion.dev/docs/videos/prores.

What it means

Thrown as ProResDecoderNotEnabledError in @remotion/media when a source is encoded with Apple ProRes but the optional ProRes decoder has not been registered. WebCodecs cannot decode ProRes natively, and unlike generic decode failures this error is unrecoverable: the preview code deliberately does NOT fall back to a native <video> element because that cannot decode ProRes either. The fix is to register the decoder from @mediabunny/prores in your entry point before registerRoot().

Source

Thrown at packages/media/src/video/video-for-preview.tsx:358

							new Error(`Network error fetching ${preloadedSrc}.`),
							`Network error fetching ${preloadedSrc}, falling back to <OffthreadVideo>`,
						);
						return;
					}

					if (result.type === 'cannot-decode') {
						handleError(
							new Error(`Cannot decode ${preloadedSrc}.`),
							`Cannot decode ${preloadedSrc}, falling back to <OffthreadVideo>`,
						);
						return;
					}

					if (result.type === 'cannot-decode-prores') {
						// Unrecoverable: a native <video> can't decode ProRes either, so
						// we must not fall back. The .catch below notifies onError and
						// rethrows without falling back.
						throw new ProResDecoderNotEnabledError(preloadedSrc);
					}

					if (result.type === 'no-tracks') {
						handleError(
							new Error(`No video or audio tracks found for ${preloadedSrc}.`),
							`No video or audio tracks found for ${preloadedSrc}, falling back to <OffthreadVideo>`,
						);
						return;
					}

					if (result.type === 'success') {
						setMediaPlayerReady(true);
						setMediaDurationInSeconds(result.durationInSeconds);

						hasDrawnRealFrameRef.current = true;
					}
				})
				.catch((error) => {

View on GitHub (pinned to 78fe4bb3fd)

Solutions

Install @mediabunny/prores and call registerProresDecoder() in your entry point (src/index.ts) before registerRoot().
Re-encode the source to H.264/H.265 if you cannot add the ProRes decoder dependency.
Confirm the registration call runs before any composition mounts (top of the entry file).

Example fix

// before (src/index.ts)
import {registerRoot} from 'remotion';
registerRoot(RemotionRoot);

// after
import {registerRoot} from 'remotion';
import {registerProresDecoder} from '@mediabunny/prores';
registerProresDecoder();
registerRoot(RemotionRoot);

Defensive patterns

Strategy: try-catch

Validate before calling

// Register the decoder once at startup (src/index.ts):
import {registerProresDecoder} from '@mediabunny/prores';
registerProresDecoder();

Type guard

import {ProResDecoderNotEnabledError} from '@remotion/media';

const isProResError = (e: unknown): e is ProResDecoderNotEnabledError =>
  e instanceof ProResDecoderNotEnabledError;

Try / catch

try {
  return <Video src={src} />;
} catch (e) {
  if (e instanceof ProResDecoderNotEnabledError) {
    // Register the decoder and re-render, or re-encode the source.
    console.error('ProRes decoder not registered. Call registerProresDecoder() in your entry point.');
  }
  throw e;
}

Prevention

Add registerProresDecoder() to your entry point any time you accept user-uploaded video.
Document the ProRes requirement for contributors who add footage.
Run a smoke render against a ProRes sample in CI to catch registration regressions.

When it happens

Trigger: Using a .mov ProRes source with <Video> in Studio preview when registerProresDecoder() has not been called. The media-player decode path returns type 'cannot-decode-prores', and video-for-preview throws this error at line 358 instead of falling back.

Common situations: Upgrading to a Remotion version that gated ProRes behind explicit registration, using ProRes footage from Final Cut Pro / DaVinci Resolve exports, or forgetting the registration call after adding @mediabunny/prores as a dependency.

Related errors

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