remotion-dev/remotion · error · Error

Expected box size of ${bytesRemaining}, got ${boxSizeRaw}. I

Error message

Expected box size of ${bytesRemaining}, got ${boxSizeRaw}. Incomplete boxes are not allowed.

What it means

Thrown early in processBox() while reading the box header. After reading the 4-byte boxSizeRaw, there are not enough bytes remaining to read the 4-byte box type (or, when boxSizeRaw===1, the 12 bytes needed for an extended 8-byte size). ISO Base Media forbids incomplete boxes, so the parser rewinds and aborts rather than read past the buffer.

Source

Thrown at packages/media-parser/src/containers/iso-base-media/process-box.ts:114

	const boxSizeRaw = iterator.getFourByteNumber();

	if (boxSizeRaw === 0) {
		return {
			type: 'box',
			box: {
				type: 'void-box',
				boxSize: 0,
			},
		};
	}

	// If `boxSize === 1`, the 8 bytes after the box type are the size of the box.
	if (
		(boxSizeRaw === 1 && iterator.bytesRemaining() < 12) ||
		iterator.bytesRemaining() < 4
	) {
		iterator.counter.decrement(iterator.counter.getOffset() - fileOffset);
		throw new Error(
			`Expected box size of ${bytesRemaining}, got ${boxSizeRaw}. Incomplete boxes are not allowed.`,
		);
	}

	const maxSize = contentLength - startOff;
	const boxType = iterator.getByteString(4, false);
	const boxSizeUnlimited =
		boxSizeRaw === 1 ? iterator.getEightByteNumber() : boxSizeRaw;
	const boxSize = Math.min(boxSizeUnlimited, maxSize);
	const headerLength = iterator.counter.getOffset() - startOff;

	if (boxType === 'mdat') {
		if (!onlyIfMdatAtomExpected) {
			return {type: 'nothing'};
		}

		const {mediaSectionState} = onlyIfMdatAtomExpected;
		mediaSectionState.addMediaSection({

View on GitHub (pinned to 78fe4bb3fd)

Solutions

Verify the source is complete: for HTTP, check Content-Length vs bytes actually received; for local files, confirm the file size matches the original.
Re-download/re-fetch the full file before parsing.
If using a custom reader/range requests, ensure it returns the full byte range the parser requests (the parser issues makeFetchMoreData requests).
Validate integrity (e.g. md5/sha256 against the source) before parsing.
Migrate to @remotion/mediabunny (parseMedia is deprecated).

Example fix

// before
const data = await fetch(url).then((r) => r.arrayBuffer());
await parseMedia({src: new Uint8Array(data), reader: webReader});

// after
const res = await fetch(url);
if (!res.ok || Number(res.headers.get('content-length')) > data.byteLength) {
  throw new Error('Incomplete download — refuse to parse a truncated file');
}
const data = await res.arrayBuffer();
await parseMedia({src: new Uint8Array(data), reader: webReader});

Defensive patterns

Strategy: validation

Validate before calling

// The cause is almost always a truncated/incomplete source. Verify the byte
// length matches the declared size before parsing.
async function assertFullyDownloaded(url: string): Promise<Uint8Array> {
  const res = await fetch(url);
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  const expected = Number(res.headers.get('content-length'));
  const buf = new Uint8Array(await res.arrayBuffer());
  if (Number.isFinite(expected) && buf.byteLength !== expected) {
    throw new Error(`Truncated download: got ${buf.byteLength} of ${expected} bytes`);
  }
  return buf;
}
// For local files, compare against a known-good size or checksum:
//   stat.size === expectedSize  (or sha256 matches)

Type guard

// A File/Uint8Array can be narrowed only by size, not by box completeness:
function isLikelyCompleteMp4Header(bytes: Uint8Array): boolean {
  // an MP4 needs at least 8 bytes for the first box header (size + type)
  return bytes.byteLength >= 8;
}

Try / catch

try {
  await parseMedia({src, reader: webReader});
} catch (err) {
  if (err instanceof Error && /Incomplete boxes are not allowed/.test(err.message)) {
    // file/stream is truncated mid-box: re-fetch the complete source
  } else {
    throw err;
  }
}

Prevention

Verify Content-Length against bytes received for every HTTP source.
For local files, confirm size/checksum against the original before parsing.
Ensure custom readers serve the full byte range the parser requests (it issues fetch-more-data).
Never parse partial range requests as if they were whole files.
Migrate to @remotion/mediabunny (parseMedia is deprecated).

When it happens

Trigger: parseMedia({src}) when the file/stream is truncated mid-box-header, or when a corrupt boxSizeRaw points beyond the available bytes. Most commonly: an incomplete HTTP download, a truncated local file, a partial range request, or a file whose last box header is only partially present.

Common situations: Truncated downloads (server dropped the connection, range request returned fewer bytes), incomplete file writes, partial fragmented segments, or corrupted size fields that overshoot EOF.

Related errors

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