{"record":{"id":"8370f225c8c0840c","repo":"SubtitleEdit/subtitleedit","slug":"output-filename-can-only-target-a-single-track","errorCode":null,"errorMessage":"--output-filename can only target a single track. Use --track-number to select one.","messagePattern":"--output-filename can only target a single track\\. Use --track-number to select one\\.","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"error","filePath":"src/seconv/Core/SubtitleConverter.cs","lineNumber":108,"sourceCode":"                        {\n                            result.Warnings.Add($\"{Path.GetFileName(inputFile)}: {warning}\");\n                        }\n\n                        if (!options.Quiet)\n                        {\n                            AnsiConsole.MarkupLine(\" [green]done.[/]\");\n                            foreach (var warning in warnings)\n                            {\n                                AnsiConsole.MarkupLineInterpolated($\"   [yellow]warning: {warning}[/]\");\n                            }\n                        }\n                    }\n                    else\n                    {\n                        // Container input (.mkv / .mp4 / .mcc) — one output per usable track\n                        if (tracks.Count > 1 && !string.IsNullOrEmpty(options.OutputFilename))\n                        {\n                            throw new InvalidOperationException(\n                                \"--output-filename can only target a single track. Use --track-number to select one.\");\n                        }\n\n                        foreach (var track in tracks)\n                        {\n                            var outputFile = ResolveOutputFileName(inputFile, options, track.LanguageCode, track.TrackNumber);\n                            var trackLabel = track.TrackNumber.HasValue ? $\"#{track.TrackNumber.Value} \" : string.Empty;\n                            var langLabel = string.IsNullOrEmpty(track.LanguageCode) ? string.Empty : $\"[{track.LanguageCode}] \";\n                            if (!options.Quiet)\n                            {\n                                AnsiConsole.MarkupInterpolated($\"[dim]{fileIndex}:[/] [cyan]{Path.GetFileName(inputFile)}[/] [yellow]{trackLabel}[/][blue]{langLabel}[/][dim]->[/] [green]{outputFile}[/]...\");\n                            }\n                            await ConvertTrackAsync(track, outputFile, options);\n                            result.SuccessfulFiles++;\n                            result.Files.Add(new FileConversionResult(inputFile, outputFile, true, null));\n                            if (!options.Quiet)\n                            {\n                                AnsiConsole.MarkupLine(\" [green]done.[/]\");","sourceCodeStart":90,"sourceCodeEnd":126,"githubUrl":"https://github.com/SubtitleEdit/subtitleedit/blob/17a9f0748781032255db3526b7215d2fb891e3af/src/seconv/Core/SubtitleConverter.cs#L90-L126","documentation":"Thrown by SubtitleConverter during container input (.mkv/.mp4/.mcc) processing when more than one usable subtitle track is discovered AND `--output-filename` is set. A single output filename cannot map to multiple input tracks without clobbering, so the converter refuses rather than silently overwriting. The fix is to select exactly one track with `--track-number`.","triggerScenarios":"Calling `ConvertAsync` with `options.OutputFilename` set on an input whose `ContainerSubtitleLoader.TryLoadTracks` returns >1 tracks. Only fires in the container branch (not single-file text/binary subtitles).","commonSituations":"Running `seconv video.mkv out.srt --output-filename=custom.srt` on an MKV with several subtitle tracks; forgetting to pass `--track-number`; assuming the first track is auto-selected when --output-filename is used.","solutions":["Add `--track-number=<n>` to select exactly one track (track numbers are listed in the discovery output).","Drop `--output-filename` so each track gets its own auto-named output.","Run the command without --output-filename first to list the available tracks and their numbers."],"exampleFix":"# before\nseconv video.mkv out --output-filename=custom.srt   # >1 track in mkv\n# after\nseconv video.mkv out --output-filename=custom.srt --track-number=2","handlingStrategy":"validation","validationCode":"// After loading tracks:\nif (!string.IsNullOrEmpty(options.OutputFilename) && tracks.Count > 1 && !options.TrackNumber.HasValue)\n    throw new ArgumentException(\"--output-filename with a multi-track container requires --track-number\");","typeGuard":"static bool IsOutputFilenameSafeForTracks(ConversionOptions o, int trackCount) =>\n    string.IsNullOrEmpty(o.OutputFilename) || trackCount <= 1 || o.TrackNumber.HasValue;","tryCatchPattern":"try { await converter.ConvertAsync(options); }\ncatch (InvalidOperationException ex) when (ex.Message.Contains(\"--output-filename can only target a single track\"))\n{\n    // require --track-number, or drop --output-filename\n}","preventionTips":["When using --output-filename on containers, always set --track-number.","If unsure of track count, omit --output-filename and use auto-naming.","Print discovered track numbers before conversion in verbose mode."],"tags":["cli","container","mkv","tracks","configuration","output"],"backgroundTag":null,"analyzedSha":"17a9f0748781032255db3526b7215d2fb891e3af","analyzedAt":"2026-08-13T18:11:43.374Z","schemaVersion":2},"datasetVersion":"2026-08-13T19:17:28.613Z"}