remotion-dev/remotion · error · Error

Unsupported STSD version ${version}

Error message

Unsupported STSD version ${version}

What it means

The STSD (Sample Description) box parser only supports version 0; any other version byte throws. STSD is always version 0 in the ISO/IEC 14496-12 spec, so a non-zero byte is almost always cursor desync from an earlier malformed box rather than a real new version.

Source

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

	samples: Sample[];
}

export const parseStsd = async ({
	offset,
	size,
	iterator,
	logLevel,
	contentLength,
}: {
	offset: number;
	size: number;
	iterator: BufferIterator;
	logLevel: MediaParserLogLevel;
	contentLength: number;
}): Promise<StsdBox> => {
	const version = iterator.getUint8();
	if (version !== 0) {
		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(

View on GitHub (pinned to 78fe4bb3fd)

Solutions

1. Validate hierarchy with `mp4box -info input.mp4` to find the broken box.
2. Re-mux: `ffmpeg -i input.mp4 -c copy -movflags +faststart remuxed.mp4`.
3. Locate the first thrown error in the parse session — that is the real root cause; the stsd version error is a symptom.
4. If streaming, ensure the entire moov (or moof+mdat segment) arrived before parsing.

Example fix

// before: earlier box size error desyncs cursor, stsd reads version 0xff
ffmpeg -i corrupt.mp4 -c copy fixed.mp4
// after: well-formed moov, stsd reads version 0

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

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

try {
  await parseMedia({src, fields: {dimensions: true}});
} catch (err) {
  if (err instanceof Error && err.message.startsWith('Unsupported STSD version')) {
    // re-mux or investigate upstream box errors
  } else throw err;
}

When it happens

Trigger: parseStsd reads a version byte != 0 at the start of an stsd box. Usually downstream of a size-miscount in a preceding box (e.g. dinf, dref, or stbl siblings) that shifted the cursor.

Common situations: Corrupt MP4 files, incomplete fragments, or files where the moov hierarchy (trak/mdia/minf/stbl) is damaged.

Related errors

• Expected ${numberOfEntries} sample descriptions, got ${boxes
• Expected stsz box in trak box
• Expected stco box in trak box
• Expected stsc box in trak box
• Expected stts box in trak box

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