remotion-dev/remotion · error · Error

expected 0 bytes ${bytesRemaining}

Error message

expected 0 bytes ${bytesRemaining}

What it means

After parsing the TFDT (Track Fragment Decode Time) box — version byte, flags, and a 32-bit or 64-bit baseMediaDecodeTime — the parser asserts zero bytes remaining. Any leftover bytes indicate an unexpected flag combination, a parser that under-read, or a malformed box with trailing data.

Source

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

export const parseTfdt = ({
	iterator,
	size,
	offset,
}: {
	iterator: BufferIterator;
	size: number;
	offset: number;
}): TfdtBox => {
	const version = iterator.getUint8();
	iterator.discard(3);
	// Flags, discard them
	const num =
		version === 0 ? iterator.getUint32() : Number(iterator.getUint64());

	const bytesRemaining = size - (iterator.counter.getOffset() - offset);

	if (bytesRemaining !== 0) {
		throw new Error('expected 0 bytes ' + bytesRemaining);
	}

	return {
		type: 'tfdt-box',
		version,
		baseMediaDecodeTime: num,
		offset,
	};
};

View on GitHub (pinned to 78fe4bb3fd)

Solutions

1. Inspect the tfdt box with `mp4dump input.mp4` to see declared size vs parsed content.
2. Re-mux the fMP4: `ffmpeg -i input.mp4 -c copy -f mp4 -movflags +faststart remuxed.mp4`.
3. If the source is a DASH/HLS segment, re-fetch the segment.
4. For live fMP4 streams, ensure segments are not being parsed mid-append.

Example fix

// before: tfdt box has trailing 4 bytes
ffmpeg -i segment.m4s -c copy -f mp4 remuxed.mp4
// after: tfdt bytesRemaining === 0

// Verify tfdt box has no trailing bytes with mp4dump before parsing
// tfdt content is 1 (version) + 3 (flags) + 4 or 8 (baseMediaDecodeTime) = 8 or 12 bytes
function expectedTfdtSize(version: number): number {
  return 8 + 4 + (version === 0 ? 4 : 8); // header + version/flags + field
}

try {
  await parseMedia({src, fields: {dimensions: true}});
} catch (err) {
  if (err instanceof Error && err.message.startsWith('expected 0 bytes') && /* tfdt context */) {
    // fMP4 tfdt has trailing bytes; re-mux or re-fetch segment
  } else throw err;
}

When it happens

Trigger: bytesRemaining = size - (currentOffset - offset) is non-zero after reading version/flags/num. Happens when the declared box size is larger than the parsed content, or when an unrecognized flag should have caused extra fields to be read.

Common situations: Corrupt or non-standard tfdt boxes in fragmented MP4 (fMP4) from DASH/HLS sources, or files from encoders that add proprietary trailing data.

Related errors

• Expected stsz box in trak box
• expected 0 bytes ${bytesRemaining}
• Unsupported TRUN version ${version}
• Unexpected data left in TRUN box: ${left}
• Expected stco box in trak box

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