jellyfin/jellyfin · error · ArgumentException

MediaSourceId is required when a specific subtitle stream is

Error message

MediaSourceId is required when a specific subtitle stream is requested

What it means

ValidateMediaOptions requires MediaOptions.MediaSourceId when a specific SubtitleStreamIndex is requested (isMediaSource true). A subtitle stream index is only meaningful for a particular media source, so an empty MediaSourceId with a set SubtitleStreamIndex is rejected.

Source

Thrown at MediaBrowser.Model/Dlna/StreamBuilder.cs:1697

            {
                throw new ArgumentException("Profile is required");
            }

            if (options.MediaSources is null)
            {
                throw new ArgumentException("MediaSources is required");
            }

            if (isMediaSource)
            {
                if (options.AudioStreamIndex.HasValue && string.IsNullOrEmpty(options.MediaSourceId))
                {
                    throw new ArgumentException("MediaSourceId is required when a specific audio stream is requested");
                }

                if (options.SubtitleStreamIndex.HasValue && string.IsNullOrEmpty(options.MediaSourceId))
                {
                    throw new ArgumentException("MediaSourceId is required when a specific subtitle stream is requested");
                }
            }
        }

        private static IEnumerable<ProfileCondition> GetProfileConditionsForVideoAudio(
            IEnumerable<CodecProfile> codecProfiles,
            string container,
            string codec,
            int? audioChannels,
            int? audioBitrate,
            int? audioSampleRate,
            int? audioBitDepth,
            string audioProfile,
            bool? isSecondaryAudio)
        {
            return codecProfiles
                .Where(profile => profile.Type == CodecType.VideoAudio &&
                    profile.ContainsAnyCodec(codec, container) &&

View on GitHub (pinned to ae8723026d)

Solutions

1. Always send MediaSourceId together with SubtitleStreamIndex.
2. Resolve the active MediaSource first, then set SubtitleStreamIndex and MediaSourceId together.
3. Validate the pairing at the API boundary and return 400 Bad Request.
4. Omit SubtitleStreamIndex when no specific source is targeted.

Example fix

// before
var options = new MediaOptions { SubtitleStreamIndex = 1, MediaSourceId = null };

// after
options.MediaSourceId = activeSource.Id;
// now safe to set SubtitleStreamIndex
options.SubtitleStreamIndex = 1;

if (options.SubtitleStreamIndex.HasValue && string.IsNullOrEmpty(options.MediaSourceId))
    throw new ArgumentException("MediaSourceId is required for a subtitle stream index");

static bool IsSubtitleStreamRequestValid(MediaOptions o) =>
    !o.SubtitleStreamIndex.HasValue || !string.IsNullOrEmpty(o.MediaSourceId);

try { _streamBuilder.BuildMediaInfo(options); }
catch (ArgumentException ex) when (ex.Message.Contains("subtitle stream"))
{ return BadRequest(ex.Message); }

When it happens

Trigger: A streaming request specifying SubtitleStreamIndex (e.g. ?SubtitleStreamIndex=1) but omitting/empty MediaSourceId while isMediaSource is true.

Common situations: Client sends a subtitle-selection param without the source id; default-subtitle logic setting SubtitleStreamIndex before resolving the source; URL builder dropping the id.

Related errors

• MediaSourceId is required when a specific audio stream is re
• Profile is required
• MediaSources is required
• Years less than or equal to 0 are invalid.
• Guid can't be empty

AI-assisted analysis of jellyfin/jellyfin@ae8723026d (2026-08-13). Data as JSON: /api/errors/ee6276973b8fdcf0. Report an issue: GitHub.