{"record":{"id":"464603349c943ec7","repo":"remotion-dev/remotion","slug":"no-tkhd-box-found","errorCode":null,"errorMessage":"No tkhd box found","messagePattern":"No tkhd box found","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/media-parser/src/metadata/metadata-from-iso.ts","lineNumber":182,"sourceCode":"\tconst meta = moov.children.find(\n\t\t(b) => b.type === 'regular-box' && b.boxType === 'meta',\n\t) as RegularBox | null;\n\tconst udta = moov.children.find(\n\t\t(b) => b.type === 'regular-box' && b.boxType === 'udta',\n\t) as RegularBox | null;\n\tconst metaInUdta = udta?.children.find((b) => {\n\t\treturn b.type === 'regular-box' && b.boxType === 'meta';\n\t}) as RegularBox | null;\n\n\tconst metaInTracks = traks\n\t\t.map((t) => {\n\t\t\tconst metaBox = t.children.find(\n\t\t\t\t(child) => child.type === 'regular-box' && child.boxType === 'meta',\n\t\t\t) as RegularBox | null;\n\t\t\tif (metaBox) {\n\t\t\t\tconst tkhd = getTkhdBox(t);\n\t\t\t\tif (!tkhd) {\n\t\t\t\t\tthrow new Error('No tkhd box found');\n\t\t\t\t}\n\n\t\t\t\treturn parseIsoMetaBox(metaBox, tkhd.trackId);\n\t\t\t}\n\n\t\t\treturn null;\n\t\t})\n\t\t.filter(truthy);\n\n\treturn [\n\t\t...(meta ? parseIsoMetaBox(meta, null) : []),\n\t\t...(metaInUdta ? parseIsoMetaBox(metaInUdta, null) : []),\n\t\t...metaInTracks.flat(1),\n\t];\n};\n","sourceCodeStart":164,"sourceCodeEnd":198,"githubUrl":"https://github.com/remotion-dev/remotion/blob/78fe4bb3fdb5a2cd68724393d63cb223db333fa7/packages/media-parser/src/metadata/metadata-from-iso.ts#L164-L198","documentation":"metadata-from-iso walks each trak looking for a child meta box; when one is found it calls getTkhdBox(t) to obtain the trackId for tagging the metadata. If a trak that contains a meta box has no tkhd (Track Header Box), it throws because the metadata cannot be associated with a track id. tkhd is mandatory in every trak per ISO-BMFF.","triggerScenarios":"Requesting metadata fields from an MP4 whose trak has a meta child but is missing the tkhd child — a malformed file. Reached when fields include metadata and the container is ISO-BMFF.","commonSituations":"Hand-edited or partially written MP4s, files produced by tools that emit meta-in-trak without full trak headers, or truncated downloads where the tkhd was lost.","solutions":["Re-mux the file to repair box structure (`ffmpeg -i in -c copy out.mp4`).","If metadata is optional, request fields without metadata and parse tracks/duration separately.","Validate with `ffprobe` before parsing; reject files ffprobe cannot read.","Report at https://remotion.dev/report if the file is otherwise valid."],"exampleFix":"// before\nconst {metadata} = await parseMedia({src: malformed, fields: {metadata: true}});\n\n// after: try without metadata, or repair first\nlet metadata;\ntry {\n  ({metadata} = await parseMedia({src, fields: {metadata: true}}));\n} catch (e) {\n  if (e.message === 'No tkhd box found') {\n    // re-mux first: ffmpeg -i src -c copy repaired.mp4\n    ({metadata} = await parseMedia({src: repaired, fields: {metadata: true}}));\n  } else throw e;\n}","handlingStrategy":"try-catch","validationCode":"import {execFileSync} from 'node:child_process';\nfunction passesProbe(path: string): boolean {\n  try { execFileSync('ffprobe', ['-v','error', path], {stdio:'pipe'}); return true; } catch { return false; }\n}","typeGuard":null,"tryCatchPattern":"let metadata;\ntry {\n  ({metadata} = await parseMedia({src, fields: {metadata: true}}));\n} catch (e) {\n  if (e instanceof Error && e.message === 'No tkhd box found') {\n    // omit metadata or re-mux the file\n    ({durationInSeconds} = await parseMedia({src, fields: {durationInSeconds: true}}));\n  } else throw e;\n}","preventionTips":["Re-mux ingested MP4s with FFmpeg to repair box structure.","Make metadata an optional field; degrade gracefully when it fails.","Validate files with ffprobe before parsing.","Report files that ffprobe accepts but the parser rejects."],"tags":["mp4","iso-bmff","metadata","corrupt-file","media-parser"],"backgroundTag":null,"analyzedSha":"78fe4bb3fdb5a2cd68724393d63cb223db333fa7","analyzedAt":"2026-08-12T17:18:50.444Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}