remotion-dev/remotion · error

Expected stsz box in trak box

Error message

Expected stsz box in trak box

What it means

Thrown by getGroupedSamplesPositionsFromMp4 when the TrakBox has no stsz (sample-size) box. stsz declares the size of each sample (or a fixed size for all); without it the parser cannot compute chunk sizes or sample counts, so it throws. The grouped-samples path specifically requires a populated stsz.

Source

Thrown at packages/media-parser/src/get-sample-positions-from-mp4.ts:34

	bigEndian,
}: {
	trakBox: TrakBox;
	bigEndian: boolean;
}): SamplePosition[] => {
	const stscBox = getStscBox(trakBox);
	const stszBox = getStszBox(trakBox);
	const stcoBox = getStcoBox(trakBox);

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

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

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

	if (stszBox.countType !== 'fixed') {
		throw new Error('Only supporting fixed count type in stsz box');
	}

	const samples: SamplePosition[] = [];

	let timestamp = 0;

	const stscKeys = Array.from(stscBox.entries.keys());
	for (let i = 0; i < stcoBox.entries.length; i++) {
		const entry = stcoBox.entries[i];
		const chunk = i + 1;
		const stscEntry = stscKeys.findLast((e) => e <= chunk);
		if (stscEntry === undefined) {
			throw new Error('should not be');
		}

View on GitHub (pinned to 78fe4bb3fd)

Solutions

1. Re-mux with ffmpeg to regenerate complete sample tables including stsz.
2. Skip traks that do not carry media samples (hint, tmcd, chapter) before computing positions.
3. Wrap in try/catch and treat the trak as unsampleable.

Example fix

// before
const positions = getGroupedSamplesPositionsFromMp4({trakBox, bigEndian});

// after
let positions = [];
try {
  positions = getGroupedSamplesPositionsFromMp4({trakBox, bigEndian});
} catch (err) {
  console.warn('trak missing stsz, skipping', err);
}

import {getStszBox} from '@remotion/media-parser/containers/iso-base-media/traversal';
if (getStszBox(trakBox)) { getGroupedSamplesPositionsFromMp4({trakBox, bigEndian}); }

const hasStsz = (trak: TrakBox): boolean => getStszBox(trak) !== null;

try { getGroupedSamplesPositionsFromMp4({trakBox, bigEndian}); } catch (e) { if (e.message === 'Expected stsz box in trak box') { /* skip trak */ } else throw e; }

When it happens

Trigger: Trak whose stbl lacks stsz. Truncated MP4s, repaired files, or traks (hint/tmcd) that legitimately omit sample sizes. Files where stsz lives in a fragment rather than the moov.

Common situations: Processing partially written MP4 files. Handling non-media traks. Encountering fragmented MP4s during early parsing.

Related errors

• Expected stsz box in trak box
• Expected stsc box in trak box
• Expected stco box in trak box
• Only supporting fixed count type in stsz box
• Expected stco box in trak box

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