remotion-dev/remotion · warning · Error

Invalid sample number size

Error message

Invalid sample number size

What it means

Thrown in readSampleNumber() while parsing a tfra box. Identical mechanism to the traf/trun checks: the 2-bit lengthSizeOfSampleNum field yields a uint width other than {8,16,32,64} (i.e. 24- or 48-bit), which is unsupported, so the sample-number size is invalid and parsing aborts.

Source

Thrown at packages/media-parser/src/containers/iso-base-media/mfra/tfra.ts:87

): number => {
	const uintTypeSampleNum = (lengthSizeOfSampleNum + 1) * 8;
	if (uintTypeSampleNum === 8) {
		return iterator.getUint8();
	}

	if (uintTypeSampleNum === 16) {
		return iterator.getUint16();
	}

	if (uintTypeSampleNum === 32) {
		return iterator.getUint32();
	}

	if (uintTypeSampleNum === 64) {
		return Number(iterator.getUint64());
	}

	throw new Error('Invalid sample number size');
};

const readTime = (iterator: BufferIterator, version: number): number => {
	if (version === 1) {
		return Number(iterator.getUint64());
	}

	return iterator.getUint32();
};

const readMoofOffset = (iterator: BufferIterator, version: number): number => {
	if (version === 1) {
		return Number(iterator.getUint64());
	}

	return iterator.getUint32();
};

View on GitHub (pinned to 78fe4bb3fd)

Solutions

1. Re-mux the fragmented file: ffmpeg -i in.mp4 -c copy -movflags +faststart out.mp4.
2. Re-fetch a clean copy if transfer corruption is suspected.
3. Avoid forcing the mfra/seeking path by limiting requested fields.
4. Migrate to @remotion/mediabunny (parseMedia is deprecated).

Example fix

// before
await parseMedia({src: fragmentedMp4, reader: nodeReader});

// after
try {
  await parseMedia({src: fragmentedMp4, reader: nodeReader});
} catch (err) {
  if (err instanceof Error && /Invalid sample number size/.test(err.message)) {
    // tfra sample-number size corrupt; re-mux the fragmented file
  } else throw err;
}

// Validate the fragmented segment before parsing:
//   ffprobe -v warning in.mp4
import {execFileSync} from 'node:child_process';
function fragmentLooksIntact(file: string): boolean {
  try {
    execFileSync('ffprobe', ['-v','warning','-hide_banner', file], {encoding:'utf8', stdio:'pipe'});
    return true;
  } catch { return false; }
}

// tfra sample-number size bits are deep binary fields; not caller-type-guardable.
// => typeGuard: null

try {
  await parseMedia({src: fragmentedMp4, reader: nodeReader});
} catch (err) {
  if (err instanceof Error && /Invalid sample number size/.test(err.message)) {
    // tfra sample-number size corrupt; re-mux the fragmented file
  } else {
    throw err;
  }
}

When it happens

Trigger: parseMedia({src}) on a fragmented MP4 whose tfra box has a corrupt sample-number size field. Only triggered when an mfra box is present and parsed.

Common situations: Corrupted fragmented MP4 (CMAF/DASH) with an mfra index; non-compliant packagers; bit corruption in the tfra size-encoding byte.

Related errors

• Invalid traf number size
• Invalid trun number size
• No video section defined
• Expected stsz box in trak box
• Expected stco box in trak box

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