{"record":{"id":"0232f5f872cbe8ba","repo":"remotion-dev/remotion","slug":"expected-tkhd-box-in-trak-box-0232f5","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-seeking-byte-from-fragmented-mp4.ts","lineNumber":73,"sourceCode":"\tconst moov = getMoovBoxFromState({\n\t\tstructureState: structure,\n\t\tisoState,\n\t\tmp4HeaderSegment,\n\t\tmayUsePrecomputed: true,\n\t});\n\tif (!moov) {\n\t\tthrow new Error('No moov atom found');\n\t}\n\n\tconst trakBox = getTrakBoxByTrackId(moov, firstTrack.trackId);\n\n\tif (!trakBox) {\n\t\tthrow new Error('No trak box found');\n\t}\n\n\tconst tkhdBox = getTkhdBox(trakBox);\n\tif (!tkhdBox) {\n\t\tthrow new Error('Expected tkhd box in trak box');\n\t}\n\n\tconst isComplete = areSamplesComplete({\n\t\tmoofBoxes: info.moofBoxes,\n\t\ttfraBoxes: info.tfraBoxes,\n\t});\n\n\tconst {samplePositions: samplePositionsArray} =\n\t\tcollectSamplePositionsFromMoofBoxes({\n\t\t\tmoofBoxes: info.moofBoxes,\n\t\t\ttkhdBox,\n\t\t\tisComplete,\n\t\t\ttrexBoxes: getTrexBoxes(moov),\n\t\t});\n\n\tLog.trace(\n\t\tlogLevel,\n\t\t'Fragmented MP4 - Checking if we have seeking info for this time range',","sourceCodeStart":55,"sourceCodeEnd":91,"githubUrl":"https://github.com/remotion-dev/remotion/blob/78fe4bb3fdb5a2cd68724393d63cb223db333fa7/packages/media-parser/src/containers/iso-base-media/get-seeking-byte-from-fragmented-mp4.ts#L55-L91","documentation":"Thrown by getSeekingByteFromFragmentedMp4 (after locating the correct trakBox by trackId) when getTkhdBox(trakBox) returns null. The targeted trak lacks a tkhd child, so the parser cannot read timescale/duration/trackId needed for sample position computation in fragmented mode. tkhd is mandatory in every trak per ISO/IEC 14496-12.","triggerScenarios":"A fragmented MP4 whose moov contains a trak that matched the trackId but has no tkhd box (or whose tkhd was parsed as another type). Reachable on the seeking path right after a successful getTrakBoxByTrackId.","commonSituations":"Corrupt fMP4 init segment with a malformed trak. Files produced by non-conformant DASH packagers. Truncated init segments. Race where a partially parsed moov is exposed before tkhd is read.","solutions":["Re-mux the init segment with a conformant packager (ffmpeg, Shaka, Bento4).","Validate the init segment with `ffprobe` and reject if tkhd is missing.","Catch the error at the seek boundary and report 'corrupt init segment'.","Ensure the moov is fully parsed before exposing its traks to the seek logic."],"exampleFix":"// before\nawait parser.seek(time);\n\n// after\ntry {\n  await parser.seek(time);\n} catch (err) {\n  if (/Expected tkhd box/i.test(String(err?.message))) {\n    throw new Error('fMP4 init segment is missing a track header (tkhd). Re-mux the init segment.');\n  }\n  throw err;\n}","handlingStrategy":"type-guard","validationCode":"import {getTkhdBox} from './traversal';\nimport type {TrakBox} from './trak/trak';\nfunction targetedTrakHasTkhd(trakBox: TrakBox): boolean {\n  return getTkhdBox(trakBox) !== null;\n}","typeGuard":"import type {TrakBox} from './trak/trak';\nimport {getTkhdBox} from './traversal';\nfunction trakHasTkhd(trakBox: TrakBox): boolean {\n  return getTkhdBox(trakBox) !== null;\n}","tryCatchPattern":"try {\n  await parser.seek(time);\n} catch (err) {\n  if (/Expected tkhd box in trak box/i.test(String(err?.message))) {\n    throw new Error('fMP4 trak is missing its tkhd header; init segment is corrupt.');\n  }\n  throw err;\n}","preventionTips":["Validate tkhd presence on the targeted trak before seeking.","Re-package fMP4 init segments with a conformant packager.","Ensure moov is fully parsed before its traks are exposed to seek logic.","Reject init segments ffprobe cannot read."],"tags":["mp4","isobmff","media-parser","fmp4","seeking","tkhd","corrupt-file"],"backgroundTag":null,"analyzedSha":"78fe4bb3fdb5a2cd68724393d63cb223db333fa7","analyzedAt":"2026-08-12T17:18:50.444Z","schemaVersion":2},"datasetVersion":"2026-08-13T19:17:28.613Z"}