What causes "Expected stts box to be ${size} bytes, but was ${bytesUsed} bytes" in remotion-dev/remotion?

Inspect the stts box with `mp4dump input.mp4` or `mp4box -dnal input.mp4` to see declared size vs entry count.

remotion-dev/remotion · error · Error

Expected stts box to be ${size} bytes, but was ${bytesUsed}

Error message

Expected stts box to be ${size} bytes, but was ${bytesUsed} bytes

What it means

After parsing all STTS entries, the parser checks that the bytes consumed exactly equal the declared box size. A mismatch means either entryCount was wrong, entries were mis-sized, or trailing garbage exists in the box. This is a structural integrity check that catches subtle corruption and cursor-drift bugs.

Source

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

	const sampleDistributions: SampleDistribution[] = [];

	// entries
	for (let i = 0; i < entryCount; i++) {
		const sampleCount = data.getUint32();
		const sampleDelta = data.getUint32();

		const sampleDistribution: SampleDistribution = {
			sampleCount,
			sampleDelta,
		};
		sampleDistributions.push(sampleDistribution);
	}

	const bytesUsed = data.counter.getOffset() - initialOffset + initialCounter;

	if (bytesUsed !== size) {
		throw new Error(
			`Expected stts box to be ${size} bytes, but was ${bytesUsed} bytes`,
		);
	}

	return {
		type: 'stts-box',
		sampleDistribution: sampleDistributions,
	};
};

View on GitHub (pinned to 78fe4bb3fd)

Solutions

Inspect the stts box with `mp4dump input.mp4` or `mp4box -dnal input.mp4` to see declared size vs entry count.
Re-mux: `ffmpeg -i input.mp4 -c copy remuxed.mp4`.
Transcode to fully regenerate timing tables: `ffmpeg -i input.mp4 -c:v libx264 -c:a aac out.mp4`.
If this is a fragmented MP4 from a live source, the segment may have been cut mid-write.

Example fix

// before: stts size header lies about entry count
ffmpeg -i corrupt.mp4 -c copy remuxed.mp4
// after: stts bytesUsed matches declared size

Defensive patterns

Strategy: try-catch

Validate before calling

// Verify stts box size vs entryCount*8+header with mp4dump before parsing
// declared_size should equal 8 (box header) + 4 (version/flags) + 4 (entryCount) + entryCount*8

Try / catch

try {
  await parseMedia({src, fields: {dimensions: true}});
} catch (err) {
  if (err instanceof Error && err.message.startsWith('Expected stts box to be')) {
    // size/count mismatch; re-mux or transcode
  } else throw err;
}

Prevention

Re-mux with ffmpeg to rebuild the stts box consistently.
Transcode to regenerate timing tables if re-mux fails.
Use mp4dump to inspect stts size/count for untrusted inputs.

When it happens

Trigger: The bytesUsed (current offset minus initial offset plus counter) does not equal the declared stts box size after reading entryCount entries.

Common situations: Files where entryCount does not match the actual number of entries that fit, padding/trailing bytes inside the stts box, or upstream cursor desync reducing available bytes.

Related errors

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