{"record":{"id":"4865fd563c01e7d2","repo":"nilaoda/N_m3u8DL-RE","slug":"a-trun-box-should-have-a-valid-flags-value","errorCode":null,"errorMessage":"A TRUN box should have a valid flags value","messagePattern":"A TRUN 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":79,"sourceCode":"                {\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                }))\n                .Parse(dataSeg,/* partialOkay= */ false);\n\n            if (!sawMDAT && !sawTFDT && !sawTRUN)\n            {\n                throw new Exception(\"A required box is missing\");\n            }\n\n            var currentTime = baseTime;\n            var reader = new BinaryReader2(new MemoryStream(rawPayload!));","sourceCodeStart":61,"sourceCodeEnd":97,"githubUrl":"https://github.com/nilaoda/N_m3u8DL-RE/blob/e113dee70c924ee08dae5460624909b04d84cb76/src/N_m3u8DL-RE.Parser/Mp4/MP4VttUtil.cs#L61-L97","documentation":"In ExtractSub, the 'trun' box's flags field must be a valid value; 1000 is the sentinel MP4Parser assigns when the flags could not be read (truncated/malformed box). The library throws before calling ParseTRUN, because flags determine which optional per-sample fields follow and an invalid value would cause misparsing.","triggerScenarios":"ExtractSub is called on a segment whose 'trun' box is cut short so the 3-byte flags field cannot be read, yielding the sentinel value 1000.","commonSituations":"Truncated downloads over unstable connections; CDN edge nodes serving partial segments; concatenating or hex-editing segment data incorrectly.","solutions":["Re-download the segment and verify integrity (size or checksum).","Validate the segment parses as complete MP4 boxes before feeding it to ExtractSub.","Ensure the downloader honors Content-Length and does not write partial files.","Use an MP4 box dumper to confirm the trun box flags (e.g. 0x000001/0x000100/0x000201)."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// ensure the segment is complete before extraction\nif (dataSeg == null || dataSeg.Length < 8) throw new ArgumentException(\"segment too small\");\n// confirm trun flags are a known value via a box scan before ExtractSub","typeGuard":"bool HasValidTrunFlags(byte[] seg) => Mp4BoxScanner.Find(seg, \"trun\") is { } b && b.Flags is 0x000001 or 0x000100 or 0x000201 or 0x000204;","tryCatchPattern":"try { var subs = MP4VttUtil.ExtractSub(dataSeg, baseTime); }\ncatch (Exception ex) when (ex.Message.Contains(\"valid flags value\")) {\n    logger.Warn(\"Malformed trun flags; re-fetching segment\");\n    dataSeg = await reDownloadAsync(segmentUrl);\n}","preventionTips":["Enforce Content-Length on segment downloads.","Retry partial downloads from the CDN.","Validate MP4 box structure before parsing.","Keep a checksum of segments from the playlist where available."],"tags":["mp4","corrupt-segment","subtitles"],"backgroundTag":"unexpected-response-shape","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"}