What causes "Unsupported level: ${level.toString(16)}" in remotion-dev/remotion?

Re-encode the video to a standard H.264 level: `ffmpeg -i input.mp4 -c:v libx264 -level 4.0 output.mp4`.

Unsupported level: ${level.toString(16)}

Error message

Unsupported level: ${level.toString(16)}

What it means

Thrown by maxMacroblockBufferSize() when the AVC (H.264) SPS level value does not appear in the internal maxMacroblocksByLevel lookup table. The table covers H.264 levels 1.0 through 6.2 (encoded as 10, 11, 12, 13, 20, 21, ..., 62). An unrecognized level means the file claims an H.264 level the parser has not mapped to a maximum macroblock buffer size, so it cannot compute buffer constraints.

Source

Thrown at packages/media-parser/src/containers/avc/max-buffer-size.ts:36

	42: 34816, // Level 4.2
	50: 110400, // Level 5.0
	51: 184320, // Level 5.1
	52: 184320, // Level 5.2
	60: 696320, // Level 6.0
	61: 696320, // Level 6.1
	62: 696320, // Level 6.2
};

export const macroBlocksPerFrame = (sps: SpsInfo) => {
	const {pic_width_in_mbs_minus1, pic_height_in_map_units_minus1} = sps;
	return (pic_width_in_mbs_minus1 + 1) * (pic_height_in_map_units_minus1 + 1);
};

export const maxMacroblockBufferSize = (sps: SpsInfo) => {
	const {level} = sps;
	const maxMacroblocks = maxMacroblocksByLevel[level];
	if (maxMacroblocks === undefined) {
		throw new Error(`Unsupported level: ${level.toString(16)}`);
	}

	return maxMacroblocks;
};

View on GitHub (pinned to 78fe4bb3fd)

Solutions

Re-encode the video to a standard H.264 level: `ffmpeg -i input.mp4 -c:v libx264 -level 4.0 output.mp4`.
Verify the file's actual codec and level with `ffprobe -show_streams input.mp4` and confirm it reports a known H.264 level.
Report the file and its SPS level value to the Remotion team so the lookup table can be extended.
Switch to Mediabunny (https://www.remotion.dev/docs/mediabunny/metadata).

Defensive patterns

Strategy: try-catch

Type guard

const KNOWN_H264_LEVELS = new Set([10, 11, 12, 13, 20, 21, 22, 30, 31, 32, 40, 41, 42, 50, 51, 52, 60, 61, 62]);

function isKnownH264Level(level: number): boolean {
  return KNOWN_H264_LEVELS.has(level);
}

Try / catch

try {
  const result = await parseMedia({src, fields: {videoCodec: true}});
} catch (e) {
  if (e instanceof Error && e.message.startsWith('Unsupported level:')) {
    console.error('H.264 level not supported. Re-encode: ffmpeg -i input.mp4 -c:v libx264 -level 4.0 output.mp4');
  } else {
    throw e;
  }
}

Prevention

Re-encode video to a standard H.264 level using ffmpeg -level flag.
Verify the H.264 level with ffprobe -show_streams before parsing.
Check for file corruption if ffprobe reports an unusual level.
Migrate to Mediabunny for broader H.264 level support.

When it happens

Trigger: Calling maxMacroblockBufferSize() with an SpsInfo object whose level field is not one of the 18 supported values (10-62 in the standard encoding). This arises from files declaring a non-standard or reserved H.264 level, or from a corrupted SPS NAL unit where the level_idc parses to an unexpected integer.

Common situations: H.264 streams with experimental or future levels not yet in the table. Files produced by encoders that write a level_idc of 0 or a reserved value. Corrupted SPS data from truncated or bit-flipped NAL units. HEVC (H.265) files misidentified as H.264 where level semantics differ.

Related errors

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