remotion-dev/remotion · error · Error

Expected ${numberOfEntries} sample descriptions, got ${boxes

Error message

Expected ${numberOfEntries} sample descriptions, got ${boxes.length}

What it means

The stsd box declares a numberOfEntries count, and after parsing child sample-entry boxes the actual parsed count must match. If they differ, either a child box failed to parse and was skipped, the box sizes are inconsistent, or the file is corrupt. This is a structural integrity check.

Source

Thrown at packages/media-parser/src/containers/iso-base-media/stsd/stsd.ts:46

		throw new Error(`Unsupported STSD version ${version}`);
	}

	// flags, we discard them
	iterator.discard(3);

	const numberOfEntries = iterator.getUint32();

	const bytesRemainingInBox = size - (iterator.counter.getOffset() - offset);

	const boxes = await parseIsoFormatBoxes({
		maxBytes: bytesRemainingInBox,
		logLevel,
		iterator,
		contentLength,
	});

	if (boxes.length !== numberOfEntries) {
		throw new Error(
			`Expected ${numberOfEntries} sample descriptions, got ${boxes.length}`,
		);
	}

	return {
		type: 'stsd-box',
		boxSize: size,
		offset,
		numberOfEntries,
		samples: boxes,
	};
};

View on GitHub (pinned to 78fe4bb3fd)

Solutions

1. Inspect stsd children with `mp4box -dnal input.mp4` or a structural MP4 inspector (e.g. mp4dump).
2. Re-mux: `ffmpeg -i input.mp4 -c copy remuxed.mp4` to rebuild the stsd consistently.
3. Transcode to regenerate sample entries: `ffmpeg -i input.mp4 -c:v libx264 -c:a aac out.mp4`.
4. Report the file upstream if a standard codec's sample entry is being skipped.

Example fix

// before: stsd declares 2 entries but only 1 parses due to bad child size
ffmpeg -i corrupt.mp4 -c copy remuxed.mp4
// after: stsd entry count matches parsed count

// Verify stsd entry count matches parsed children with mp4dump before parsing
// mp4dump input.mp4 | grep -A30 stsd → compare numberOfEntries to child box count

try {
  await parseMedia({src, fields: {dimensions: true}});
} catch (err) {
  if (err instanceof Error && err.message.startsWith('Expected ') && err.message.includes('sample descriptions')) {
    // structural mismatch; re-mux or transcode
  } else throw err;
}

When it happens

Trigger: parseStsd reads numberOfEntries, then parseIsoFormatBoxes returns a boxes array whose length differs. Common when a child sample entry has an inconsistent size causing it to be mis-parsed or skipped.

Common situations: Files with malformed sample entries, sizes that don't align, or where an unknown codec FourCC caused an inner parse to bail early.

Related errors

• Unsupported STSD version ${version}
• Expected stts box to be ${size} bytes, but was ${bytesUsed}
• Unexpected data left in TRUN box: ${left}
• Expected stsz box in trak box
• Expected stco box in trak box

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