{"record":{"id":"977c043b46f94586","repo":"remotion-dev/remotion","slug":"unsupported-hdlr-version-version","errorCode":null,"errorMessage":"Unsupported hdlr version: ${version}","messagePattern":"Unsupported hdlr version: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/media-parser/src/containers/iso-base-media/meta/hdlr.ts","lineNumber":21,"sourceCode":"\nexport interface HdlrBox extends BaseBox {\n\ttype: 'hdlr-box';\n\thdlrType: string;\n\tcomponentName: string;\n}\nexport const parseHdlr = ({\n\titerator,\n\tsize,\n\toffset,\n}: {\n\titerator: BufferIterator;\n\tsize: number;\n\toffset: number;\n}): Promise<HdlrBox> => {\n\tconst box = iterator.startBox(size - 8);\n\tconst version = iterator.getUint8();\n\tif (version !== 0) {\n\t\tthrow new Error(`Unsupported hdlr version: ${version}`);\n\t}\n\n\t// version\n\titerator.discard(3);\n\t// predefined\n\titerator.discard(4);\n\t// type\n\tconst hdlrType = iterator.getByteString(4, false);\n\t// component manufactor\n\titerator.discard(4);\n\t// component flags\n\titerator.discard(4);\n\t// component flags mask\n\titerator.discard(4);\n\t// component name\n\tconst componentName = iterator.readUntilNullTerminator();\n\tbox.discardRest();\n","sourceCodeStart":3,"sourceCodeEnd":39,"githubUrl":"https://github.com/remotion-dev/remotion/blob/78fe4bb3fdb5a2cd68724393d63cb223db333fa7/packages/media-parser/src/containers/iso-base-media/meta/hdlr.ts#L3-L39","documentation":"Thrown in parseHdlr() after reading the hdlr box version byte. The ISO/QuickTime spec defines only version 0 for the hdlr (handler reference) box; any other value is rejected. The hdlr box declares a track's handler type (vide/soun/meta/...), so a wrong version would corrupt track-type detection downstream.","triggerScenarios":"parseMedia({src}) on a file whose hdlr box carries a non-zero version byte — typically byte corruption, a truncated hdlr, or a non-standard muxer writing an unsupported version.","commonSituations":"Corrupted files (bit-flips in the version byte), files produced by experimental/non-compliant muxers, or files damaged in transfer.","solutions":["Re-mux the file: ffmpeg -i in.file -c copy out.mp4 to regenerate compliant hdlr boxes.","Re-fetch the source if you suspect transfer corruption.","Validate with MP4Box -info or ffprobe and replace the file if the box is unreadable.","Switch to @remotion/mediabunny (parseMedia is deprecated)."],"exampleFix":"// before\nawait parseMedia({src, reader: nodeReader});\n\n// after\ntry {\n  await parseMedia({src, reader: nodeReader});\n} catch (err) {\n  if (err instanceof Error && /Unsupported hdlr version/.test(err.message)) {\n    // re-mux to regenerate a version-0 hdlr box\n  } else throw err;\n}","handlingStrategy":"try-catch","validationCode":"// Validate the file with ffprobe; a corrupt hdlr usually produces warnings:\n//   ffprobe -v warning in.mp4\nimport {execFileSync} from 'node:child_process';\nfunction fileLooksIntact(file: string): boolean {\n  try {\n    execFileSync('ffprobe', ['-v','warning','-hide_banner', file], {encoding: 'utf8', stdio:'pipe'});\n    return true;\n  } catch { return false; }\n}","typeGuard":"// The hdlr version byte is a deep binary field; not type-guardable from the caller.\n// => typeGuard: null","tryCatchPattern":"try {\n  await parseMedia({src, reader: nodeReader});\n} catch (err) {\n  if (err instanceof Error && /Unsupported hdlr version/.test(err.message)) {\n    // re-mux to regenerate a version-0 hdlr box\n  } else {\n    throw err;\n  }\n}","preventionTips":["Re-mux files with ffmpeg to regenerate compliant handler boxes.","Re-fetch sources suspected of transfer corruption.","Validate with ffprobe/MP4Box before parsing.","Migrate to @remotion/mediabunny (parseMedia is deprecated)."],"tags":["mp4","iso-base-media","media-parser","hdlr","corrupt-file","box-version"],"backgroundTag":null,"analyzedSha":"78fe4bb3fdb5a2cd68724393d63cb223db333fa7","analyzedAt":"2026-08-12T17:18:50.444Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}