What causes "Expected stsz box in trak box" in remotion-dev/remotion?

Re-mux the file to ensure a complete moov with standard boxes: `ffmpeg -i input.mp4 -c copy -movflags faststart output.mp4`.

remotion-dev/remotion · error · Error

Expected stsz box in trak box

Error message

Expected stsz box in trak box

What it means

Thrown by collectSamplePositionsFromTrak() when an MP4/ISOBMFF trak (track) box does not contain an stsz (Sample Sizes) box. The stsz box stores the byte size of every media sample in the track and is required for sample-position computation. Its absence means the track box is structurally incomplete or non-standard, and the parser cannot determine where individual samples begin and end.

Source

Thrown at packages/media-parser/src/containers/iso-base-media/collect-sample-positions-from-trak.ts:34

	const shouldGroupSamples = shouldGroupAudioSamples(trakBox);
	const timescaleAndDuration = getTimescaleAndDuration(trakBox);

	if (shouldGroupSamples) {
		return getGroupedSamplesPositionsFromMp4({
			trakBox,
			bigEndian: shouldGroupSamples.bigEndian,
		});
	}

	const stszBox = getStszBox(trakBox);
	const stcoBox = getStcoBox(trakBox);
	const stscBox = getStscBox(trakBox);
	const stssBox = getStssBox(trakBox);
	const sttsBox = getSttsBox(trakBox);
	const cttsBox = getCttsBox(trakBox);

	if (!stszBox) {
		throw new Error('Expected stsz box in trak box');
	}

	if (!stcoBox) {
		throw new Error('Expected stco box in trak box');
	}

	if (!stscBox) {
		throw new Error('Expected stsc box in trak box');
	}

	if (!sttsBox) {
		throw new Error('Expected stts box in trak box');
	}

	if (!timescaleAndDuration) {
		throw new Error('Expected timescale and duration in trak box');
	}

View on GitHub (pinned to 78fe4bb3fd)

Solutions

Re-mux the file to ensure a complete moov with standard boxes: `ffmpeg -i input.mp4 -c copy -movflags faststart output.mp4`.
If the file is fragmented MP4, convert to a non-fragmented format: `ffmpeg -i input.mp4 -c copy -movflags +faststart output.mp4`.
Switch to Mediabunny (https://www.remotion.dev/docs/mediabunny/metadata) which may handle fragmented MP4.
Verify the file structure with `ffprobe -show_format -show_streams input.mp4` to confirm it's parseable.
Report the file to the Remotion team if standard tools handle it but parseMedia does not.

Defensive patterns

Strategy: try-catch

Try / catch

try {
  const result = await parseMedia({src, fields: {durationInSeconds: true}});
} catch (e) {
  if (e instanceof Error && e.message === 'Expected stsz box in trak box') {
    console.error('MP4 trak box missing stsz. File may be fragmented MP4 or corrupt. Re-mux: ffmpeg -i input.mp4 -c copy -movflags +faststart output.mp4');
  } else {
    throw e;
  }
}

Prevention

Verify MP4 files with `ffprobe -show_streams` before parsing.
Re-mux fragmented MP4 files to non-fragmented format for compatibility.
Use ffmpeg -movflags +faststart to ensure a complete moov atom with standard boxes.
Migrate to Mediabunny which has better fragmented MP4 support.

When it happens

Trigger: Parsing an MP4/M4A/MOV/WebM (ISOBMFF) file where a trak box lacks the mandatory stsz box. This can occur with fragment-only MP4s (fMP4) that store sample sizes in a traf/moof fragment instead of the moov/trak, with non-standard or corrupt files, or with files using alternative sample-size mechanisms.

Common situations: Fragmented MP4 files (used in DASH/HLS streaming) where sample sizes live in moof/traf fragments, not in the moov/trak. Corrupt MP4 files with truncated moov boxes. Files produced by non-standard muxers that omit stsz. Files with only stz2 (compact sample sizes) instead of stsz.

Related errors

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