What causes "Unsupported STSD version ${version}" in remotion-dev/remotion?

Validate: `mp4box -info input.mp4` or `ffprobe -v error input.mp4`.

remotion-dev/remotion · error · Error

Unsupported STSD version ${version}

Error message

Unsupported STSD version ${version}

What it means

The STSZ (Sample Size) box parser only supports version 0; any other version throws. The message text incorrectly says 'STSD version' (copy-paste bug) but the box is STSZ. Since STSZ is spec-version-0 only, a non-zero byte signals corruption or cursor desync.

Source

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

export type StszBox = BaseBox & {
	type: 'stsz-box';
	version: number;
	flags: number[];
	sampleCount: number;
} & Discriminated;

export const parseStsz = ({
	iterator,
	offset,
	size,
}: {
	iterator: BufferIterator;
	offset: number;
	size: number;
}): StszBox => {
	const version = iterator.getUint8();
	if (version !== 0) {
		throw new Error(`Unsupported STSD version ${version}`);
	}

	const flags = iterator.getSlice(3);

	const sampleSize = iterator.getUint32();
	const sampleCount = iterator.getUint32();

	if (sampleSize !== 0) {
		return {
			type: 'stsz-box',
			boxSize: size,
			offset,
			version,
			flags: [...flags],
			sampleCount,
			countType: 'fixed',
			sampleSize,
		};

View on GitHub (pinned to 78fe4bb3fd)

Solutions

Validate: `mp4box -info input.mp4` or `ffprobe -v error input.mp4`.
Re-mux: `ffmpeg -i input.mp4 -c copy -movflags +faststart remuxed.mp4`.
Trace earlier thrown errors first — they are the likely root cause.
Ensure full segment delivery for streaming sources.

Example fix

// before: cursor shift makes stsz read version 0x10
ffmpeg -i corrupt.mp4 -c copy fixed.mp4
// after: stsz reads version 0

Defensive patterns

Strategy: try-catch

Validate before calling

function isValidStszVersion(v: number): boolean {
  return v === 0;
}

Type guard

function isStszVersionZero(v: number): v is 0 {
  return v === 0;
}

Try / catch

try {
  await parseMedia({src, fields: {dimensions: true}});
} catch (err) {
  if (err instanceof Error && err.message.startsWith('Unsupported STSD version') && /* stsz context */) {
    // ambiguous message also used by stco/stsc; re-mux to resolve
  } else throw err;
}

Prevention

Re-mux suspicious files with ffmpeg.
Treat 'Unsupported STSD version' as ambiguous across stco/stsc/stsz — use box context.
Investigate earlier errors first.

When it happens

Trigger: parseStsz reads a version byte != 0 at the start of an stsz box. Usually downstream of a sizing error in a sibling stbl box.

Common situations: Corrupt MP4/MOV files, partial downloads, or damaged moov tables.

Related errors

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