{"record":{"id":"eb251d50720977fc","repo":"remotion-dev/remotion","slug":"unexpected-box-type-bytestring","errorCode":null,"errorMessage":"Unexpected box type ${byteString}","messagePattern":"Unexpected box type (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"warning","filePath":"packages/media-parser/src/containers/iso-base-media/stsd/colr.ts","lineNumber":76,"sourceCode":"\t\t\tfullRangeFlag: false,\n\t\t\tmatrixIndex,\n\t\t\tprimaries,\n\t\t\ttransfer,\n\t\t};\n\t}\n\n\tif (byteString === 'prof') {\n\t\tconst profile = iterator.getSlice(size - 12);\n\n\t\treturn {\n\t\t\ttype: 'colr-box',\n\t\t\tcolorType: 'icc-profile',\n\t\t\tprofile,\n\t\t\tparsed: parseIccProfile(profile),\n\t\t};\n\t}\n\n\tthrow new Error('Unexpected box type ' + byteString);\n};\n","sourceCodeStart":58,"sourceCodeEnd":78,"githubUrl":"https://github.com/remotion-dev/remotion/blob/78fe4bb3fdb5a2cd68724393d63cb223db333fa7/packages/media-parser/src/containers/iso-base-media/stsd/colr.ts#L58-L78","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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.","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.","Wrap the parse call in try/catch and fall back to a different demuxer or to parseMediaOnWebWorker with a tolerant mode if available.","Verify with `ffprobe -show_packets -show_data in.mp4 | grep -i colr` which color type the file actually carries."],"exampleFix":"// before: file carries nclx colr box, parse throws\n// ffmpeg remux to drop nclx metadata\nffmpeg -i input.mp4 -c copy -map_metadata -1 -color_primaries 2 -color_trc 2 -colorspace 2 output.mp4","handlingStrategy":"try-catch","validationCode":"// Pre-check the colr box colorType before handing off to parseMedia\nimport {createBuffer} from '@remotion/media-parser';\n// Inspect the raw bytes of the colr box header; offset 8-12 is the colorType FourCC\nfunction colrBoxColorType(boxBytes: Uint8Array): string {\n  return String.fromCharCode(boxBytes[8], boxBytes[9], boxBytes[10], boxBytes[11]);\n}\nconst ct = colrBoxColorType(colrBoxBytes);\nif (ct !== 'prof') {\n  // will throw in current parser — handle before calling parseMedia\n}","typeGuard":"function isSupportedColrType(colorType: string): colorType is 'prof' {\n  return colorType === 'prof';\n}","tryCatchPattern":"try {\n  const result = await parseMedia({src, fields: {dimensions: true}});\n} catch (err) {\n  if (err instanceof Error && err.message.startsWith('Unexpected box type')) {\n    // color type unsupported (likely 'nclx'); fall back to ffprobe or skip color metadata\n  } else throw err;\n}","preventionTips":["Normalize source files with ffmpeg before parsing to strip unsupported color box types.","Maintain a list of known-unsupported colorTypes and skip files that carry them upstream.","When accepting user uploads, validate with ffprobe and re-mux non-conforming files."],"tags":["media-parser","isobmff","colr-box","parser-coverage","mp4"],"backgroundTag":null,"analyzedSha":"78fe4bb3fdb5a2cd68724393d63cb223db333fa7","analyzedAt":"2026-08-12T17:18:50.444Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}