{"record":{"id":"531d79ffcfb055bb","repo":"remotion-dev/remotion","slug":"expected-tkhd-box-in-trak-box","errorCode":null,"errorMessage":"Expected tkhd box in trak box","messagePattern":"Expected tkhd box in trak box","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/media-parser/src/containers/iso-base-media/get-sample-positions-from-track.ts","lineNumber":22,"sourceCode":"import {collectSamplePositionsFromTrak} from './collect-sample-positions-from-trak';\nimport type {TrexBox} from './moov/trex';\nimport type {TrakBox} from './trak/trak';\nimport {getTkhdBox} from './traversal';\n\nexport const getSamplePositionsFromTrack = ({\n\ttrakBox,\n\tmoofBoxes,\n\tmoofComplete,\n\ttrexBoxes,\n}: {\n\ttrakBox: TrakBox;\n\tmoofBoxes: MoofBox[];\n\tmoofComplete: boolean;\n\ttrexBoxes: TrexBox[];\n}): {samplePositions: SamplePosition[]; isComplete: boolean} => {\n\tconst tkhdBox = getTkhdBox(trakBox);\n\tif (!tkhdBox) {\n\t\tthrow new Error('Expected tkhd box in trak box');\n\t}\n\n\tif (moofBoxes.length > 0) {\n\t\tconst {samplePositions} = collectSamplePositionsFromMoofBoxes({\n\t\t\tmoofBoxes,\n\t\t\ttkhdBox,\n\t\t\tisComplete: moofComplete,\n\t\t\ttrexBoxes,\n\t\t});\n\n\t\treturn {\n\t\t\tsamplePositions: samplePositions.map((s) => s.samples).flat(1),\n\t\t\tisComplete: moofComplete,\n\t\t};\n\t}\n\n\treturn {\n\t\tsamplePositions: collectSamplePositionsFromTrak(trakBox),","sourceCodeStart":4,"sourceCodeEnd":40,"githubUrl":"https://github.com/remotion-dev/remotion/blob/78fe4bb3fdb5a2cd68724393d63cb223db333fa7/packages/media-parser/src/containers/iso-base-media/get-sample-positions-from-track.ts#L4-L40","documentation":"Thrown by getSamplePositionsFromTrack when getTkhdBox(trakBox) returns null. The tkhd (Track Header) box is mandatory in every trak per ISO/IEC 14496-12 and carries the trackId used to correlate moof fragments with their track. Without it the parser cannot compute sample positions for either fragmented or progressive paths.","triggerScenarios":"A trak box whose children do not include a tkhd-box, or whose tkhd was misparsed as a different box type. Reachable from both the moof-based and progressive branches of getSamplePositionsFromTrack since the check runs before branching.","commonSituations":"Corrupt moov/trak structure. Files from non-conformant muxers. Truncated files. Test fixtures with hand-crafted traks that omit tkhd.","solutions":["Re-mux with ffmpeg `-c copy -movflags faststart` to rebuild tkhd and the full trak.","Validate with `ffprobe` and reject malformed files upstream.","Catch the error and report the file as unsupported.","If authoring traks programmatically, always include a tkhd box as the first child of trak."],"exampleFix":"// before\nconst { samplePositions } = getSamplePositionsFromTrack({ trakBox, moofBoxes, moofComplete, trexBoxes });\n\n// after\ntry {\n  const { samplePositions } = getSamplePositionsFromTrack({ trakBox, moofBoxes, moofComplete, trexBoxes });\n} catch (err) {\n  throw new Error(`Track is missing its header (tkhd). File is corrupt; re-mux with ffmpeg.`);\n}","handlingStrategy":"type-guard","validationCode":"import type {TrakBox} from './trak/trak';\nimport {getTkhdBox} from './traversal';\nfunction trakHasTkhd(trakBox: TrakBox): boolean {\n  return getTkhdBox(trakBox) !== null;\n}","typeGuard":"import type {TrakBox} from './trak/trak';\nimport type {TkhdBox} from './tkhd';\nimport {getTkhdBox} from './traversal';\nfunction trakWithTkhd(trakBox: TrakBox): trakBox is TrakBox & { __tkhd: TkhdBox } {\n  return getTkhdBox(trakBox) !== null;\n}","tryCatchPattern":"try {\n  const { samplePositions } = getSamplePositionsFromTrack({ trakBox, moofBoxes, moofComplete, trexBoxes });\n} catch (err) {\n  if (/Expected tkhd box/i.test(String(err?.message))) {\n    throw new Error('trak is missing its tkhd header; file is corrupt, re-mux with ffmpeg.');\n  }\n  throw err;\n}","preventionTips":["Always validate tkhd presence before passing a trak into sample-position logic.","Re-mux user uploads with faststart to rebuild the full trak structure.","Catch tkhd errors at the API boundary and emit a single 'unsupported file' message.","Ensure your test fixtures include a tkhd in every trak."],"tags":["mp4","isobmff","media-parser","trak","tkhd","corrupt-file"],"backgroundTag":null,"analyzedSha":"78fe4bb3fdb5a2cd68724393d63cb223db333fa7","analyzedAt":"2026-08-12T17:18:50.444Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}