{"record":{"id":"ee6276973b8fdcf0","repo":"jellyfin/jellyfin","slug":"mediasourceid-is-required-when-a-specific-subtitle","errorCode":null,"errorMessage":"MediaSourceId is required when a specific subtitle stream is requested","messagePattern":"MediaSourceId is required when a specific subtitle stream is requested","errorType":"validation","errorClass":"ArgumentException","httpStatus":null,"severity":"error","filePath":"MediaBrowser.Model/Dlna/StreamBuilder.cs","lineNumber":1697,"sourceCode":"            {\n                throw new ArgumentException(\"Profile is required\");\n            }\n\n            if (options.MediaSources is null)\n            {\n                throw new ArgumentException(\"MediaSources is required\");\n            }\n\n            if (isMediaSource)\n            {\n                if (options.AudioStreamIndex.HasValue && string.IsNullOrEmpty(options.MediaSourceId))\n                {\n                    throw new ArgumentException(\"MediaSourceId is required when a specific audio stream is requested\");\n                }\n\n                if (options.SubtitleStreamIndex.HasValue && string.IsNullOrEmpty(options.MediaSourceId))\n                {\n                    throw new ArgumentException(\"MediaSourceId is required when a specific subtitle stream is requested\");\n                }\n            }\n        }\n\n        private static IEnumerable<ProfileCondition> GetProfileConditionsForVideoAudio(\n            IEnumerable<CodecProfile> codecProfiles,\n            string container,\n            string codec,\n            int? audioChannels,\n            int? audioBitrate,\n            int? audioSampleRate,\n            int? audioBitDepth,\n            string audioProfile,\n            bool? isSecondaryAudio)\n        {\n            return codecProfiles\n                .Where(profile => profile.Type == CodecType.VideoAudio &&\n                    profile.ContainsAnyCodec(codec, container) &&","sourceCodeStart":1679,"sourceCodeEnd":1715,"githubUrl":"https://github.com/jellyfin/jellyfin/blob/ae8723026d97b6d0f926638803edef338919b794/MediaBrowser.Model/Dlna/StreamBuilder.cs#L1679-L1715","documentation":"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.","triggerScenarios":"A streaming request specifying SubtitleStreamIndex (e.g. ?SubtitleStreamIndex=1) but omitting/empty MediaSourceId while isMediaSource is true.","commonSituations":"Client sends a subtitle-selection param without the source id; default-subtitle logic setting SubtitleStreamIndex before resolving the source; URL builder dropping the id.","solutions":["Always send MediaSourceId together with SubtitleStreamIndex.","Resolve the active MediaSource first, then set SubtitleStreamIndex and MediaSourceId together.","Validate the pairing at the API boundary and return 400 Bad Request.","Omit SubtitleStreamIndex when no specific source is targeted."],"exampleFix":"// before\nvar options = new MediaOptions { SubtitleStreamIndex = 1, MediaSourceId = null };\n\n// after\noptions.MediaSourceId = activeSource.Id;\n// now safe to set SubtitleStreamIndex\noptions.SubtitleStreamIndex = 1;","handlingStrategy":"validation","validationCode":"if (options.SubtitleStreamIndex.HasValue && string.IsNullOrEmpty(options.MediaSourceId))\n    throw new ArgumentException(\"MediaSourceId is required for a subtitle stream index\");","typeGuard":"static bool IsSubtitleStreamRequestValid(MediaOptions o) =>\n    !o.SubtitleStreamIndex.HasValue || !string.IsNullOrEmpty(o.MediaSourceId);","tryCatchPattern":"try { _streamBuilder.BuildMediaInfo(options); }\ncatch (ArgumentException ex) when (ex.Message.Contains(\"subtitle stream\"))\n{ return BadRequest(ex.Message); }","preventionTips":["Always pair SubtitleStreamIndex with MediaSourceId.","Set both fields together after resolving the active source.","Validate at the API boundary."],"tags":["dlna","streaming","validation","subtitle-stream","media-source-id"],"backgroundTag":null,"analyzedSha":"ae8723026d97b6d0f926638803edef338919b794","analyzedAt":"2026-08-13T10:43:30.013Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}