SubtitleEdit/subtitleedit · error · InvalidOperationException

--output-filename can only target a single track. Use --trac

Error message

--output-filename can only target a single track. Use --track-number to select one.

What it means

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`.

Source

Thrown at src/seconv/Core/SubtitleConverter.cs:108

                        {
                            result.Warnings.Add($"{Path.GetFileName(inputFile)}: {warning}");
                        }

                        if (!options.Quiet)
                        {
                            AnsiConsole.MarkupLine(" [green]done.[/]");
                            foreach (var warning in warnings)
                            {
                                AnsiConsole.MarkupLineInterpolated($"   [yellow]warning: {warning}[/]");
                            }
                        }
                    }
                    else
                    {
                        // Container input (.mkv / .mp4 / .mcc) — one output per usable track
                        if (tracks.Count > 1 && !string.IsNullOrEmpty(options.OutputFilename))
                        {
                            throw new InvalidOperationException(
                                "--output-filename can only target a single track. Use --track-number to select one.");
                        }

                        foreach (var track in tracks)
                        {
                            var outputFile = ResolveOutputFileName(inputFile, options, track.LanguageCode, track.TrackNumber);
                            var trackLabel = track.TrackNumber.HasValue ? $"#{track.TrackNumber.Value} " : string.Empty;
                            var langLabel = string.IsNullOrEmpty(track.LanguageCode) ? string.Empty : $"[{track.LanguageCode}] ";
                            if (!options.Quiet)
                            {
                                AnsiConsole.MarkupInterpolated($"[dim]{fileIndex}:[/] [cyan]{Path.GetFileName(inputFile)}[/] [yellow]{trackLabel}[/][blue]{langLabel}[/][dim]->[/] [green]{outputFile}[/]...");
                            }
                            await ConvertTrackAsync(track, outputFile, options);
                            result.SuccessfulFiles++;
                            result.Files.Add(new FileConversionResult(inputFile, outputFile, true, null));
                            if (!options.Quiet)
                            {
                                AnsiConsole.MarkupLine(" [green]done.[/]");

View on GitHub (pinned to 17a9f07487)

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.

Example fix

# before
seconv video.mkv out --output-filename=custom.srt   # >1 track in mkv
# after
seconv video.mkv out --output-filename=custom.srt --track-number=2

Defensive patterns

Strategy: validation

Validate before calling

// After loading tracks:
if (!string.IsNullOrEmpty(options.OutputFilename) && tracks.Count > 1 && !options.TrackNumber.HasValue)
    throw new ArgumentException("--output-filename with a multi-track container requires --track-number");

Type guard

static bool IsOutputFilenameSafeForTracks(ConversionOptions o, int trackCount) =>
    string.IsNullOrEmpty(o.OutputFilename) || trackCount <= 1 || o.TrackNumber.HasValue;

Try / catch

try { await converter.ConvertAsync(options); }
catch (InvalidOperationException ex) when (ex.Message.Contains("--output-filename can only target a single track"))
{
    // require --track-number, or drop --output-filename
}

Prevention

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.

When it happens

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

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

Related errors

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