remotion-dev/remotion · error · Error

Unsupported STSS version ${version}

Error message

Unsupported STSS version ${version}

What it means

The STSS (Sync Sample / keyframe table) box parser only supports version 0; any other version byte throws. STSS is spec-defined as version 0 only, so a non-zero byte indicates corruption or cursor desync from an earlier mis-parsed box.

Source

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

export interface StssBox extends BaseBox {
	type: 'stss-box';
	version: number;
	flags: number[];
	sampleNumber: Set<number>;
}

export const parseStss = ({
	iterator,
	offset,
	boxSize,
}: {
	iterator: BufferIterator;
	offset: number;
	boxSize: number;
}): StssBox => {
	const version = iterator.getUint8();
	if (version !== 0) {
		throw new Error(`Unsupported STSS version ${version}`);
	}

	const flags = iterator.getSlice(3);
	const sampleCount = iterator.getUint32();

	const sampleNumber: Set<number> = new Set();
	for (let i = 0; i < sampleCount; i++) {
		sampleNumber.add(iterator.getUint32());
	}

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

	if (bytesRemainingInBox > 0) {
		iterator.discard(bytesRemainingInBox);
	}

	return {
		type: 'stss-box',

View on GitHub (pinned to 78fe4bb3fd)

Solutions

1. Run `mp4box -info input.mp4` to locate the corruption.
2. Re-mux with ffmpeg: `ffmpeg -i input.mp4 -c copy remuxed.mp4`.
3. Investigate earlier parse errors in the same run first.
4. For fragmented streams, confirm segment completeness.

Example fix

// before: stss version reads 0x80 due to upstream desync
ffmpeg -i corrupt.mp4 -c copy fixed.mp4
// after: stss parses with version 0

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

function isStssVersionZero(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 STSS version')) {
    // corrupt stss or upstream desync; re-mux
  } else throw err;
}

When it happens

Trigger: parseStss reads a version byte != 0. Typically a symptom of an earlier box in the stbl leaving the cursor at the wrong offset.

Common situations: Corrupt MP4 files, files with damaged moov tables, or files where the stbl box ordering/sizing is off.

Related errors

• Expected stsz box in trak box
• Expected stco box in trak box
• Expected stsc box in trak box
• Expected stts box in trak box
• Expected timescale and duration in trak box

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