SubtitleEdit/subtitleedit · error · InvalidOperationException

Image-based formats require ConversionOptions

Error message

Image-based formats require ConversionOptions

What it means

Thrown when an image-based output format (BDN-XML, Blu-ray sup, DOST, WebVTT thumbnail, etc.) is selected but ConversionOptions is null. Image rendering requires resolution, rendering parameters, and font/style settings from ConversionOptions — there is no safe default for all of them, so a null options object is rejected at the call site with `options ?? throw ...`.

Source

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

                {
                    sb.AppendLine();
                }
                sb.AppendLine(text);
            }
            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);
        }

View on GitHub (pinned to 17a9f07487)

Solutions

1. Construct a ConversionOptions (at minimum with Resolution set, e.g. 1920x1080) before exporting to any image-based format.
2. On the CLI, ensure --resolution or the relevant image flags are passed so options is non-null.
3. If you have a default resolution in mind, pass new ConversionOptions { Resolution = (1920, 1080) }.

Example fix

// before
LibSEIntegration.SaveSubtitle(sub, outPath, "BDN-XML", null);

// after
LibSEIntegration.SaveSubtitle(sub, outPath, "BDN-XML", new ConversionOptions { Resolution = (1920, 1080) });

if (ImageOutputWriter.TryCreateHandler(formatName) is not null && options == null)
    throw new InvalidOperationException("Image-based formats require non-null ConversionOptions.");

static bool IsImageFormat(string formatName) => ImageOutputWriter.TryCreateHandler(formatName) is not null;

try { LibSEIntegration.SaveSubtitle(sub, outPath, formatName, options); }
catch (InvalidOperationException ex) when (ex.Message.Contains("Image-based formats require ConversionOptions"))
{ /* construct ConversionOptions with Resolution and retry */ }

When it happens

Trigger: Calling the save path with an image-format formatName and passing null for options. In the CLI this means no ConversionOptions were constructed (or the --resolution / image-related flags were absent and the options object was never initialized).

Common situations: Programmatic caller forgot to construct ConversionOptions for an image export; CLI code path that builds options lazily but skipped it for image formats; a refactor that made options optional but didn't account for image formats needing it.

Related errors

• No paragraphs to render.
• No bitmaps to write.
• Custom text output requires --custom-format=<path-to-templat
• No Blu-Ray sup subtitles found in: {filePath}
• No PGS subtitles in MKV track #{track.TrackNumber}.

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