SubtitleEdit/subtitleedit · error · InvalidOperationException

Invalid Matroska file: {filePath}

Error message

Invalid Matroska file: {filePath}

What it means

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.

Source

Thrown at src/seconv/Core/ContainerSubtitleLoader.cs:242

            if (options.TrackNumbers.Count > 0)
            {
                throw new InvalidOperationException(
                    $"MXF contained {subtitleTexts.Count} essence(s) but none matched --track-number ({string.Join(",", options.TrackNumbers)}): {filePath}");
            }
            throw new InvalidOperationException(
                $"MXF contained {subtitleTexts.Count} candidate subtitle essence(s) but none parsed as a known format: {filePath}");
        }

        return tracks;
    }

    private static List<LoadedTrack> LoadMatroska(string filePath, ConversionOptions options)
    {
        var tracks = new List<LoadedTrack>();
        using var matroska = new MatroskaFile(filePath);
        if (!matroska.IsValid)
        {
            throw new InvalidOperationException($"Invalid Matroska file: {filePath}");
        }

        var subtitleTracks = matroska.GetTracks(true);
        if (subtitleTracks.Count == 0)
        {
            throw new InvalidOperationException($"No subtitle tracks in Matroska file: {filePath}");
        }

        foreach (var track in subtitleTracks)
        {
            if (options.ForcedOnly && !track.IsForced)
            {
                continue;
            }
            if (options.TrackNumbers.Count > 0 && !options.TrackNumbers.Contains(track.TrackNumber))
            {
                continue;
            }

View on GitHub (pinned to 17a9f07487)

Solutions

1. Verify the file is a real Matroska with ffprobe/mkvinfo.
2. Re-download or re-mux the source if the header is corrupt/truncated.
3. If the extension is wrong, rename it to the true format so the loader routes it correctly.

// Validate the Matroska header before delegating to the loader.
using var mk = new MatroskaFile(filePath);
if (!mk.IsValid) return Error($"Not a valid Matroska file: {filePath}");

try { tracks = ContainerSubtitleLoader.TryLoadTracks(filePath, options); }
catch (InvalidOperationException ex) when (ex.Message.Contains("Invalid Matroska file"))
{ Console.Error.WriteLine(ex.Message); return; }

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• No VobSub subtitles in MKV track #{track.TrackNumber}.
• No subtitle tracks in Matroska file: {filePath}
• No PGS subtitles in MKV track #{track.TrackNumber}.
• --output-filename can only target a single track. Use --trac
• No PGS subtitles in MKV track #{track.TrackNumber}.

AI-assisted analysis of SubtitleEdit/subtitleedit@17a9f07487 (2026-08-13). Data as JSON: /api/errors/f03d64f0ef25c116. Report an issue: GitHub.