{"record":{"id":"5c5e0e80af55bc1d","repo":"nilaoda/N_m3u8DL-RE","slug":"a-tfhd-box-should-have-a-valid-flags-value","errorCode":null,"errorMessage":"A TFHD box should have a valid flags value","messagePattern":"A TFHD box should have a valid flags value","errorType":"exception","errorClass":"Exception","httpStatus":null,"severity":"error","filePath":"src/N_m3u8DL-RE.Parser/Mp4/MP4VttUtil.cs","lineNumber":70,"sourceCode":"            ulong defaultDuration = 0;\n            List<Sample> presentations = [];\n\n\n            // parse media\n            new MP4Parser()\n                .Box(\"moof\", MP4Parser.Children)\n                .Box(\"traf\", MP4Parser.Children)\n                .FullBox(\"tfdt\", box =>\n                {\n                    sawTFDT = true;\n                    if (box.Version is not (0 or 1))\n                        throw new Exception(\"TFDT version can only be 0 or 1\");\n                    baseTime = MP4Parser.ParseTFDT(box.Reader, box.Version);\n                })\n                .FullBox(\"tfhd\", box =>\n                {\n                    if (box.Flags == 1000)\n                        throw new Exception(\"A TFHD box should have a valid flags value\");\n                    defaultDuration = MP4Parser.ParseTFHD(box.Reader, box.Flags).DefaultSampleDuration;\n                })\n                .FullBox(\"trun\", box =>\n                {\n                    sawTRUN = true;\n                    if (box.Version == 1000)\n                        throw new Exception(\"A TRUN box should have a valid version value\");\n                    if (box.Flags == 1000)\n                        throw new Exception(\"A TRUN box should have a valid flags value\");\n                    presentations = MP4Parser.ParseTRUN(box.Reader, box.Version, box.Flags).SampleData;\n                })\n                .Box(\"mdat\", MP4Parser.AllData(data =>\n                {\n                    if (sawMDAT)\n                        throw new Exception(\"VTT cues in mp4 with multiple MDAT are not currently supported\");\n                    sawMDAT = true;\n                    rawPayload = data;\n                }))","sourceCodeStart":52,"sourceCodeEnd":88,"githubUrl":"https://github.com/nilaoda/N_m3u8DL-RE/blob/e113dee70c924ee08dae5460624909b04d84cb76/src/N_m3u8DL-RE.Parser/Mp4/MP4VttUtil.cs#L52-L88","documentation":"ExtractSub's 'tfhd' FullBox handler demands a valid flags value before calling MP4Parser.ParseTFHD; the sentinel 1000 is used by the parser to signal 'flags could not be read'. Receiving it means the Track Fragment Header box is malformed or was misparsed, so default sample duration/description info cannot be trusted.","triggerScenarios":"Calling ExtractSub on a media segment whose moof/traf/tfhd box reports Flags == 1000 (the parser's 'invalid/absent flags' sentinel), i.e. the tfhd box is too short, corrupt, or misaligned.","commonSituations":"Corrupt/truncated media fragment, bytes misinterpreted as fMP4 (e.g. a TS or WebM chunk fed to the MP4 parser), or a muxer writing nonstandard tfhd boxes.","solutions":["Re-download the affected media segment; corruption is the most common cause.","Verify the fragments really are MP4/fMP4 (not TS or another container) before feeding them to ExtractSub.","Dump the fragment with MP4Box/Bento4 to inspect the tfhd box structure.","Catch the exception and skip the broken fragment instead of aborting subtitle extraction."],"exampleFix":"// before\nvar sub = MP4VttUtil.ExtractSub(segmentFiles, timescale); // throws on bad tfhd\n\n// after\ntry\n{\n    var sub = MP4VttUtil.ExtractSub(segmentFiles, timescale);\n}\ncatch (Exception ex) when (ex.Message.Contains(\"TFHD box should have a valid flags\"))\n{\n    Log.Warning(\"Fragment has malformed tfhd box; skipping it\");\n}","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try { var sub = MP4VttUtil.ExtractSub(files, ts); }\ncatch (Exception ex) when (ex.Message.Contains(\"TFHD box should have a valid flags\"))\n{ Log.Warning(\"Fragment has malformed tfhd; skipping\"); }","preventionTips":["Verify fragment integrity (container sniffing) before feeding to the MP4 parser.","Do not pass non-MP4 containers (TS/WebM) to MP4VttUtil.","Skip-and-log per fragment so a single malformed box doesn't abort extraction."],"tags":["mp4","fmp4","parsing","subtitle"],"backgroundTag":"invalid-flag-value","analyzedSha":"e113dee70c924ee08dae5460624909b04d84cb76","analyzedAt":"2026-09-13T02:43:21.078Z","contentChangedAt":"2026-09-13T02:43:21.078Z","schemaVersion":2},"datasetVersion":"2026-09-16T09:17:16.951Z"}