remotion-dev/remotion · error · Error

Unsupported hdlr version: ${version}

Error message

Unsupported hdlr version: ${version}

What it means

Thrown in parseHdlr() after reading the hdlr box version byte. The ISO/QuickTime spec defines only version 0 for the hdlr (handler reference) box; any other value is rejected. The hdlr box declares a track's handler type (vide/soun/meta/...), so a wrong version would corrupt track-type detection downstream.

Source

Thrown at packages/media-parser/src/containers/iso-base-media/meta/hdlr.ts:21

export interface HdlrBox extends BaseBox {
	type: 'hdlr-box';
	hdlrType: string;
	componentName: string;
}
export const parseHdlr = ({
	iterator,
	size,
	offset,
}: {
	iterator: BufferIterator;
	size: number;
	offset: number;
}): Promise<HdlrBox> => {
	const box = iterator.startBox(size - 8);
	const version = iterator.getUint8();
	if (version !== 0) {
		throw new Error(`Unsupported hdlr version: ${version}`);
	}

	// version
	iterator.discard(3);
	// predefined
	iterator.discard(4);
	// type
	const hdlrType = iterator.getByteString(4, false);
	// component manufactor
	iterator.discard(4);
	// component flags
	iterator.discard(4);
	// component flags mask
	iterator.discard(4);
	// component name
	const componentName = iterator.readUntilNullTerminator();
	box.discardRest();

View on GitHub (pinned to 78fe4bb3fd)

Solutions

1. Re-mux the file: ffmpeg -i in.file -c copy out.mp4 to regenerate compliant hdlr boxes.
2. Re-fetch the source if you suspect transfer corruption.
3. Validate with MP4Box -info or ffprobe and replace the file if the box is unreadable.
4. Switch to @remotion/mediabunny (parseMedia is deprecated).

Example fix

// before
await parseMedia({src, reader: nodeReader});

// after
try {
  await parseMedia({src, reader: nodeReader});
} catch (err) {
  if (err instanceof Error && /Unsupported hdlr version/.test(err.message)) {
    // re-mux to regenerate a version-0 hdlr box
  } else throw err;
}

// Validate the file with ffprobe; a corrupt hdlr usually produces warnings:
//   ffprobe -v warning in.mp4
import {execFileSync} from 'node:child_process';
function fileLooksIntact(file: string): boolean {
  try {
    execFileSync('ffprobe', ['-v','warning','-hide_banner', file], {encoding: 'utf8', stdio:'pipe'});
    return true;
  } catch { return false; }
}

// The hdlr version byte is a deep binary field; not type-guardable from the caller.
// => typeGuard: null

try {
  await parseMedia({src, reader: nodeReader});
} catch (err) {
  if (err instanceof Error && /Unsupported hdlr version/.test(err.message)) {
    // re-mux to regenerate a version-0 hdlr box
  } else {
    throw err;
  }
}

When it happens

Trigger: parseMedia({src}) on a file whose hdlr box carries a non-zero version byte — typically byte corruption, a truncated hdlr, or a non-standard muxer writing an unsupported version.

Common situations: Corrupted files (bit-flips in the version byte), files produced by experimental/non-compliant muxers, or files damaged in transfer.

Related errors

• Could not find number of channels
• Could not find sample rate
• No video sample
• Could not find video codec
• No video section defined

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