{"record":{"id":"f03d64f0ef25c116","repo":"SubtitleEdit/subtitleedit","slug":"invalid-matroska-file-filepath","errorCode":null,"errorMessage":"Invalid Matroska file: {filePath}","messagePattern":"Invalid Matroska file: (.+?)","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"error","filePath":"src/seconv/Core/ContainerSubtitleLoader.cs","lineNumber":242,"sourceCode":"            if (options.TrackNumbers.Count > 0)\n            {\n                throw new InvalidOperationException(\n                    $\"MXF contained {subtitleTexts.Count} essence(s) but none matched --track-number ({string.Join(\",\", options.TrackNumbers)}): {filePath}\");\n            }\n            throw new InvalidOperationException(\n                $\"MXF contained {subtitleTexts.Count} candidate subtitle essence(s) but none parsed as a known format: {filePath}\");\n        }\n\n        return tracks;\n    }\n\n    private static List<LoadedTrack> LoadMatroska(string filePath, ConversionOptions options)\n    {\n        var tracks = new List<LoadedTrack>();\n        using var matroska = new MatroskaFile(filePath);\n        if (!matroska.IsValid)\n        {\n            throw new InvalidOperationException($\"Invalid Matroska file: {filePath}\");\n        }\n\n        var subtitleTracks = matroska.GetTracks(true);\n        if (subtitleTracks.Count == 0)\n        {\n            throw new InvalidOperationException($\"No subtitle tracks in Matroska file: {filePath}\");\n        }\n\n        foreach (var track in subtitleTracks)\n        {\n            if (options.ForcedOnly && !track.IsForced)\n            {\n                continue;\n            }\n            if (options.TrackNumbers.Count > 0 && !options.TrackNumbers.Contains(track.TrackNumber))\n            {\n                continue;\n            }","sourceCodeStart":224,"sourceCodeEnd":260,"githubUrl":"https://github.com/SubtitleEdit/subtitleedit/blob/17a9f0748781032255db3526b7215d2fb891e3af/src/seconv/Core/ContainerSubtitleLoader.cs#L224-L260","documentation":"Thrown by LoadMatroska when the opened MatroskaFile reports IsValid == false — the EBML/Matroska header signature could not be found, so the file is not a genuine .mkv/.mks. There is no point reading tracks from an invalid container, so the loader aborts immediately.","triggerScenarios":"Calling the .mkv/.mks load path on a file that is not a valid Matroska — MatroskaFile(filePath).IsValid returns false at ContainerSubtitleLoader.cs:240. Happens with corrupt headers, truncated files, or a non-Matroska file given a .mkv extension.","commonSituations":"A renamed file (e.g. an .mp4 renamed to .mkv); a partially downloaded/truncated MKV; a corrupt EBML header from a faulty muxer or interrupted write.","solutions":["Verify the file is a real Matroska with ffprobe/mkvinfo.","Re-download or re-mux the source if the header is corrupt/truncated.","If the extension is wrong, rename it to the true format so the loader routes it correctly."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// Validate the Matroska header before delegating to the loader.\nusing var mk = new MatroskaFile(filePath);\nif (!mk.IsValid) return Error($\"Not a valid Matroska file: {filePath}\");","typeGuard":null,"tryCatchPattern":"try { tracks = ContainerSubtitleLoader.TryLoadTracks(filePath, options); }\ncatch (InvalidOperationException ex) when (ex.Message.Contains(\"Invalid Matroska file\"))\n{ Console.Error.WriteLine(ex.Message); return; }","preventionTips":["Pre-check MatroskaFile.IsValid before the full load, or verify with ffprobe/mkvinfo.","Catch the InvalidOperationException and skip the file in batch runs.","Ensure files are fully downloaded/muxed before conversion."],"tags":["matroska","mkv","invalid-file","container"],"backgroundTag":null,"analyzedSha":"17a9f0748781032255db3526b7215d2fb891e3af","analyzedAt":"2026-08-13T18:11:43.374Z","schemaVersion":2},"datasetVersion":"2026-08-13T19:17:28.613Z"}