yt-dlp/yt-dlp · error · ExtractorError

{self.IE_NAME} returned error: {media_selection_error.id}

Error message

{self.IE_NAME} returned error: {media_selection_error.id}

What it means

Raised by BBCCoUkIE._raise_extractor_error (yt_dlp/extractor/bbc.py:314) when the media-selector JSON for a programme contains a 'result' field - the BBC's own error signal - which _extract_mediasas turns into MediaSelectionError. The error id is echoed in the message; the classic value is 'geolocation' for UK-only programmes. Marked expected=True.

Source

Thrown at yt_dlp/extractor/bbc.py:314

        for connection in self._extract_connections(media):
            cc_url = url_or_none(connection.get('href'))
            if not cc_url:
                continue
            captions = self._download_xml(
                cc_url, programme_id, 'Downloading captions', fatal=False)
            if not isinstance(captions, xml.etree.ElementTree.Element):
                continue
            subtitles['en'] = [
                {
                    'url': connection.get('href'),
                    'ext': 'ttml',
                },
            ]
            break
        return subtitles

    def _raise_extractor_error(self, media_selection_error):
        raise ExtractorError(
            f'{self.IE_NAME} returned error: {media_selection_error.id}',
            expected=True)

    def _download_media_selector(self, programme_id):
        last_exception = None
        formats, subtitles = [], {}
        for media_set in self._MEDIA_SETS:
            try:
                fmts, subs = self._download_media_selector_url(
                    self._MEDIA_SELECTOR_URL_TEMPL % (media_set, programme_id), programme_id)
                formats.extend(fmts)
                if subs:
                    self._merge_subtitles(subs, target=subtitles)
            except BBCCoUkIE.MediaSelectionError as e:
                if e.id in ('notukerror', 'geolocation', 'selectionunavailable'):
                    last_exception = e
                    continue
                self._raise_extractor_error(e)

View on GitHub (pinned to 81ecd58b13)

Solutions

If the id is 'geolocation', route through a UK proxy/VPN: yt-dlp --proxy socks5://... and retry
Confirm the programme plays on the BBC site from the same network
Update yt-dlp (yt-dlp -U) in case selector endpoints changed
For non-geo ids, report the programme URL and error id at https://github.com/yt-dlp/yt-dlp/issues

Example fix

# before
ydl_opts = {}

# after: present a UK IP for geo-locked BBC programmes
ydl_opts = {'proxy': 'socks5://uk-proxy.example.com:1080'}

Defensive patterns

Strategy: fallback

Validate before calling

import urllib.request

def appears_uk():
    return 'GB' in urllib.request.urlopen('https://ipinfo.io/json').read().decode()

Try / catch

from yt_dlp.utils import ExtractorError

try:
    info = ydl.extract_info(url, download=False)
except ExtractorError as e:
    if 'returned error: geolocation' in str(e):
        with YoutubeDL({'proxy': UK_PROXY}) as ydl_uk:
            info = ydl_uk.extract_info(url, download=False)
    else:
        raise

Prevention

Configure a UK proxy for BBC iPlayer jobs up front
Check the error id in the message - only 'geolocation' is proxy-fixable
Verify programmes play on bbc.co.uk from the same egress IP before extracting

When it happens

Trigger: Requesting a media set for a programme the BBC will not serve to your IP: geolocation restrictions on iPlayer/Sounds content, or unavailable media sets; the loop over _MEDIA_SETS at bbc.py:320 catches MediaSelectionError and re-raises via this method only after every set fails.

Common situations: Downloading BBC iPlayer/radio programmes from outside the UK without a proxy; UK-only sport and rights-restricted content; programmes whose media sets have been pulled.

Related errors

AI-assisted analysis of yt-dlp/yt-dlp@81ecd58b13 (2026-08-22). Data as JSON: /api/errors/165a9a4d24ba1c37. Report an issue: GitHub.