SubtitleEdit/subtitleedit · error · InvalidOperationException

Unknown subtitle format: {formatName}

Error message

Unknown subtitle format: {formatName}

What it means

Thrown when the requested output format name does not match any registered subtitle format AND is not recognized as an image-based format by TryCreateHandler. ResolveFormatByName returns null for unrecognized names, and the ?? throw fires. This is a user-facing format identifier error — the formatName string could not be resolved to any SubtitleFormat or image handler.

Source

Thrown at src/seconv/Core/LibSEIntegration.cs:454

            File.WriteAllText(filePath, sb.ToString(), plainEncoding);
            return;
        }

        // Image-based output formats: render text → bitmaps → format-specific bytes
        var imageHandler = ImageOutputWriter.TryCreateHandler(formatName);
        if (imageHandler is not null)
        {
            var outputDirImg = Path.GetDirectoryName(filePath);
            if (!string.IsNullOrEmpty(outputDirImg) && !Directory.Exists(outputDirImg))
            {
                Directory.CreateDirectory(outputDirImg);
            }
            ImageOutputWriter.Write(subtitle, filePath, imageHandler, options ?? throw new InvalidOperationException("Image-based formats require ConversionOptions"));
            return;
        }

        var targetFormat = ResolveFormatByName(formatName)
            ?? throw new InvalidOperationException($"Unknown subtitle format: {formatName}");

        // Strip native source-format markup that the target wouldn't understand
        if (sourceFormat != null && !sourceFormat.GetType().Equals(targetFormat.GetType()))
        {
            targetFormat.RemoveNativeFormatting(subtitle, sourceFormat);
        }

        var outputDir = Path.GetDirectoryName(filePath);
        if (!string.IsNullOrEmpty(outputDir) && !Directory.Exists(outputDir))
        {
            Directory.CreateDirectory(outputDir);
        }

        // Ebu (binary) — optional header file
        if (targetFormat is Ebu ebu)
        {
            Ebu.EbuGeneralSubtitleInformation? header = null;
            if (!string.IsNullOrEmpty(ebuHeaderFile))

View on GitHub (pinned to 17a9f07487)

Solutions

1. Check the exact format name spelling and casing — use the format list/enum from seconv's documentation or --help output.
2. If unsure of the canonical name, try common aliases (e.g. 'SubRip', 'srt', 'SRT').
3. Update seconv to the latest version — the format may have been added recently.

Example fix

// before
LibSEIntegration.SaveSubtitle(sub, outPath, "subrib", options);

// after
LibSEIntegration.SaveSubtitle(sub, outPath, "srt", options); // or "SubRip"

var resolved = LibSEIntegration.ResolveFormatByName(formatName);
if (resolved == null && ImageOutputWriter.TryCreateHandler(formatName) == null)
    throw new InvalidOperationException($"Unknown subtitle format: {formatName}");

static bool IsKnownFormat(string formatName) => LibSEIntegration.ResolveFormatByName(formatName) != null || ImageOutputWriter.TryCreateHandler(formatName) != null;

try { LibSEIntegration.SaveSubtitle(sub, outPath, formatName, options); }
catch (InvalidOperationException ex) when (ex.Message.Contains("Unknown subtitle format"))
{ /* list supported formats, prompt user for correct name */ }

When it happens

Trigger: Calling the save path with a formatName that is misspelled, uses the wrong casing/dialect, or names a format the bundled LibSE version does not support. The image handler lookup (TryCreateHandler) also returned null, so it is neither a text nor image format.

Common situations: Typo in the format name on the CLI (e.g. 'srtt' instead of 'srt'); using an informal name vs the canonical one (e.g. 'ssa' vs 'Advanced Sub Station Alpha'); requesting a format added in a newer LibSE build than the one seconv bundles.

Related errors

• No Blu-Ray sup subtitles found in: {filePath}
• No PGS subtitles in MKV track #{track.TrackNumber}.
• No VobSub subtitle packs in: {subPath}
• No paragraphs to render.
• No bitmaps to write.

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