{"record":{"id":"be6118bb5a86b555","repo":"SubtitleEdit/subtitleedit","slug":"image-based-formats-require-conversionoptions","errorCode":null,"errorMessage":"Image-based formats require ConversionOptions","messagePattern":"Image-based formats require ConversionOptions","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"error","filePath":"src/seconv/Core/LibSEIntegration.cs","lineNumber":449,"sourceCode":"                {\n                    sb.AppendLine();\n                }\n                sb.AppendLine(text);\n            }\n            File.WriteAllText(filePath, sb.ToString(), plainEncoding);\n            return;\n        }\n\n        // Image-based output formats: render text → bitmaps → format-specific bytes\n        var imageHandler = ImageOutputWriter.TryCreateHandler(formatName);\n        if (imageHandler is not null)\n        {\n            var outputDirImg = Path.GetDirectoryName(filePath);\n            if (!string.IsNullOrEmpty(outputDirImg) && !Directory.Exists(outputDirImg))\n            {\n                Directory.CreateDirectory(outputDirImg);\n            }\n            ImageOutputWriter.Write(subtitle, filePath, imageHandler, options ?? throw new InvalidOperationException(\"Image-based formats require ConversionOptions\"));\n            return;\n        }\n\n        var targetFormat = ResolveFormatByName(formatName)\n            ?? throw new InvalidOperationException($\"Unknown subtitle format: {formatName}\");\n\n        // Strip native source-format markup that the target wouldn't understand\n        if (sourceFormat != null && !sourceFormat.GetType().Equals(targetFormat.GetType()))\n        {\n            targetFormat.RemoveNativeFormatting(subtitle, sourceFormat);\n        }\n\n        var outputDir = Path.GetDirectoryName(filePath);\n        if (!string.IsNullOrEmpty(outputDir) && !Directory.Exists(outputDir))\n        {\n            Directory.CreateDirectory(outputDir);\n        }\n","sourceCodeStart":431,"sourceCodeEnd":467,"githubUrl":"https://github.com/SubtitleEdit/subtitleedit/blob/17a9f0748781032255db3526b7215d2fb891e3af/src/seconv/Core/LibSEIntegration.cs#L431-L467","documentation":"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 ...`.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Construct a ConversionOptions (at minimum with Resolution set, e.g. 1920x1080) before exporting to any image-based format.","On the CLI, ensure --resolution or the relevant image flags are passed so options is non-null.","If you have a default resolution in mind, pass new ConversionOptions { Resolution = (1920, 1080) }."],"exampleFix":"// before\nLibSEIntegration.SaveSubtitle(sub, outPath, \"BDN-XML\", null);\n\n// after\nLibSEIntegration.SaveSubtitle(sub, outPath, \"BDN-XML\", new ConversionOptions { Resolution = (1920, 1080) });","handlingStrategy":"validation","validationCode":"if (ImageOutputWriter.TryCreateHandler(formatName) is not null && options == null)\n    throw new InvalidOperationException(\"Image-based formats require non-null ConversionOptions.\");","typeGuard":"static bool IsImageFormat(string formatName) => ImageOutputWriter.TryCreateHandler(formatName) is not null;","tryCatchPattern":"try { LibSEIntegration.SaveSubtitle(sub, outPath, formatName, options); }\ncatch (InvalidOperationException ex) when (ex.Message.Contains(\"Image-based formats require ConversionOptions\"))\n{ /* construct ConversionOptions with Resolution and retry */ }","preventionTips":["Always construct ConversionOptions (with at least Resolution) for image-format exports.","In your pipeline, check TryCreateHandler(formatName) to determine if options are mandatory.","Default to new ConversionOptions { Resolution = (1920, 1080) } when the user does not specify."],"tags":["image-export","missing-config","null-argument","validation","subtitles"],"backgroundTag":null,"analyzedSha":"17a9f0748781032255db3526b7215d2fb891e3af","analyzedAt":"2026-08-13T18:11:43.374Z","schemaVersion":2},"datasetVersion":"2026-08-13T19:17:28.613Z"}