remotion-dev/remotion · warning · Error

Unexpected box type ${byteString}

Error message

Unexpected box type ${byteString}

What it means

Thrown by the colr (color) box parser when the 4-byte color type code is neither 'prof' (ICC profile) nor any other handled type. The parser currently only handles the 'prof' branch; any other colorType byte string (most notably 'nclx' for NCLX color information, which is extremely common in modern MP4 files) causes this throw. This is effectively a parser-coverage limitation: the file is well-formed but the library does not implement that color type.

Source

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

			fullRangeFlag: false,
			matrixIndex,
			primaries,
			transfer,
		};
	}

	if (byteString === 'prof') {
		const profile = iterator.getSlice(size - 12);

		return {
			type: 'colr-box',
			colorType: 'icc-profile',
			profile,
			parsed: parseIccProfile(profile),
		};
	}

	throw new Error('Unexpected box type ' + byteString);
};

View on GitHub (pinned to 78fe4bb3fd)

Solutions

1. If you control the file: re-mux without NCLX color metadata, e.g. ffmpeg -i in.mp4 -c copy -movflags +faststart -color_primaries unspecified -color_trc unspecified -colorspace unspecified out.mp4, or strip the colr box entirely.
2. If you cannot control the file: report the file upstream to the media-parser project so 'nclx' parsing is added; this is a feature gap, not a corrupt-file error.
3. Wrap the parse call in try/catch and fall back to a different demuxer or to parseMediaOnWebWorker with a tolerant mode if available.
4. Verify with `ffprobe -show_packets -show_data in.mp4 | grep -i colr` which color type the file actually carries.

Example fix

// before: file carries nclx colr box, parse throws
// ffmpeg remux to drop nclx metadata
ffmpeg -i input.mp4 -c copy -map_metadata -1 -color_primaries 2 -color_trc 2 -colorspace 2 output.mp4

// Pre-check the colr box colorType before handing off to parseMedia
import {createBuffer} from '@remotion/media-parser';
// Inspect the raw bytes of the colr box header; offset 8-12 is the colorType FourCC
function colrBoxColorType(boxBytes: Uint8Array): string {
  return String.fromCharCode(boxBytes[8], boxBytes[9], boxBytes[10], boxBytes[11]);
}
const ct = colrBoxColorType(colrBoxBytes);
if (ct !== 'prof') {
  // will throw in current parser — handle before calling parseMedia
}

function isSupportedColrType(colorType: string): colorType is 'prof' {
  return colorType === 'prof';
}

try {
  const result = await parseMedia({src, fields: {dimensions: true}});
} catch (err) {
  if (err instanceof Error && err.message.startsWith('Unexpected box type')) {
    // color type unsupported (likely 'nclx'); fall back to ffprobe or skip color metadata
  } else throw err;
}

When it happens

Trigger: Parsing an MP4/MOV whose stsd sample entry contains a colr box whose colorType field is 'nclx' (or any value other than 'prof'). The throw happens at colr.ts:76 after the 'prof' check fails.

Common situations: Modern phones (iPhone, Pixel) and most hardware encoders write 'nclx' color boxes for HDR/SDR color primaries, transfer characteristics, and matrix coefficients. Any file produced by modern ffmpeg with -movflags or color metadata will trip this. Files with custom or non-ICC color profiles also hit it.

Related errors

• Unsupported version ${version}
• Unknown sample format ${boxFormat}
• Expected sampleDescriptionIndex to be 1, but got ${sampleDes
• 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/eb251d50720977fc. Report an issue: GitHub.