What causes "Expected Layer I, II or III" in remotion-dev/remotion?

Validate the file with `ffprobe -i file.mp3` to confirm it's genuine MPEG audio.

remotion-dev/remotion · error · Error

Expected Layer I, II or III

Error message

Expected Layer I, II or III

What it means

Thrown by `innerParseMp3PacketHeader` when the 2-bit layer field equals `0b00`, which is marked 'reserved' in the MPEG specification. Valid layer values are `0b01` (Layer III), `0b10` (Layer II), and `0b11` (Layer I); `0b00` is forbidden.

Source

Thrown at packages/media-parser/src/containers/mp3/parse-packet-header.ts:206

	if (
		audioVersionId !== 0b11 &&
		audioVersionId !== 0b10 &&
		audioVersionId !== 0b00
	) {
		throw new Error('Expected MPEG Version 1 or 2');
	}

	const mpegVersion = audioVersionId === 0b11 ? 1 : (2 as MpegVersion);

	const layerBits = iterator.getBits(2);
	/**
   * 00 - reserved
     01 - Layer III
     10 - Layer II
     11 - Layer I
   */
	if (layerBits === 0b00) {
		throw new Error('Expected Layer I, II or III');
	}

	const layer = layerBits === 0b11 ? 1 : layerBits === 0b10 ? 2 : 3;

	iterator.getBits(1); // 0b1 means that there is no CRC, 0b0 means there is. Not validating checksum though

	const bitrateIndex = iterator.getBits(4);
	const bitrateInKbit = getBitrateKB({
		bits: bitrateIndex,
		mpegVersion,
		level: layer as Level,
	});
	if (bitrateInKbit === 'bad') {
		throw new Error('Invalid bitrate');
	}

	if (bitrateInKbit === 'free') {
		throw new Error('Free bitrate not supported');

View on GitHub (pinned to 78fe4bb3fd)

Solutions

Validate the file with `ffprobe -i file.mp3` to confirm it's genuine MPEG audio.
Re-encode the file from a source that produces valid MPEG Layer II or III audio.
Check for partial downloads, disk corruption, or transfer errors.
Report the file at remotion.dev/report if it triggers this on a seemingly valid MP3.

Example fix

# verify and re-encode
ffprobe -v error -i input.mp3
ffmpeg -i input.mp3 -codec:a libmp3lame output.mp3

Defensive patterns

Strategy: try-catch

Try / catch

try {
  await parseMedia({src, fields: {durationInSeconds: true}});
} catch (e) {
  if (e instanceof Error && e.message === 'Expected Layer I, II or III') {
    console.error('The MP3 frame header contains a reserved MPEG layer value.');
  }
  throw e;
}

Prevention

Validate MP3 files with ffprobe to confirm valid MPEG layer bits.
Re-encode files from a known-good source if frame headers are corrupt.
Check for data corruption from incomplete downloads.
Use try-catch around parseMedia for untrusted files.

When it happens

Trigger: During frame header parsing (`parse-packet-header.ts:205-207`), the `layerBits` field (read after the audio version ID) is `0b00`. No MPEG layer maps to this value.

Common situations: Corrupt or damaged frame headers. Non-MPEG data being interpreted as an audio frame. Files with bit-level corruption. Random byte sequences encountered during parsing due to offset misalignment.

Related errors

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