ytdl-org/youtube-dl · error · ExtractorError

An extractor error has occurred.

Error message

An extractor error has occurred.

What it means

Raised by InfoExtractor.extract when _real_extract dies with an uncaught KeyError or StopIteration. These two exception types are treated as 'extractor looked up a key/next() that does not exist' — i.e. the page's data did not match what the extractor expected. It is NOT marked expected: it signals a broken or outdated extractor, and the original traceback is attached as cause.

Source

Thrown at youtube_dl/extractor/common.py:587

        """Extracts URL information and returns it in list of dicts."""
        try:
            for _ in range(2):
                try:
                    self.initialize()
                    ie_result = self._real_extract(url)
                    if self._x_forwarded_for_ip:
                        ie_result['__x_forwarded_for_ip'] = self._x_forwarded_for_ip
                    return ie_result
                except GeoRestrictedError as e:
                    if self.__maybe_fake_ip_and_retry(e.countries):
                        continue
                    raise
        except ExtractorError:
            raise
        except compat_http_client.IncompleteRead as e:
            raise ExtractorError('A network error has occurred.', cause=e, expected=True)
        except (KeyError, StopIteration) as e:
            raise ExtractorError('An extractor error has occurred.', cause=e)

    def __maybe_fake_ip_and_retry(self, countries):
        if (not self.get_param('geo_bypass_country', None)
                and self._GEO_BYPASS
                and self.get_param('geo_bypass', True)
                and not self._x_forwarded_for_ip
                and countries):
            country_code = random.choice(countries)
            self._x_forwarded_for_ip = GeoUtils.random_ipv4(country_code)
            if self._x_forwarded_for_ip:
                self.report_warning(
                    'Video is geo restricted. Retrying extraction with fake IP %s (%s) as X-Forwarded-For.'
                    % (self._x_forwarded_for_ip, country_code.upper()))
                return True
        return False

    def set_downloader(self, downloader):
        """Sets the downloader for this IE."""

View on GitHub (pinned to 956b8c5855)

Solutions

  1. Update youtube-dl (youtube-dl -U) — extractor fixes for site changes land constantly.
  2. If already current, switch to yt-dlp, which is actively maintained.
  3. Reproduce with -v (--verbose) and check the cause traceback to see which lookup failed; report or patch the extractor.
  4. Verify the URL is the right type for the extractor you are hitting (wrong-URL dispatch can trigger the same crash).

Example fix

# before
info = ydl.extract_info(url)  # KeyError -> 'An extractor error has occurred.'

# after: run verbose to find the failing lookup, then report/patch
youtube_dl -v <url>   # traceback shows e.g. KeyError: 'formats'
Defensive patterns

Strategy: try-catch

Try / catch

from youtube_dl.utils import ExtractorError
try:
    info = ydl.extract_info(url)
except ExtractorError as e:
    if not e.expected and isinstance(e.cause, (KeyError, StopIteration)):
        report_broken_extractor(url, str(e.cause))  # extractor bug, not user error
    raise

Prevention

When it happens

Trigger: A site changed its JSON keys or HTML structure so a dict['key'] lookup or next(iterator) inside the extractor fails — e.g. renaming 'formats', missing 'url' in an entry, iterating an empty generator. Any site-layout drift manifests here.

Common situations: Running an old youtube-dl against redesigned sites (the dominant cause); race where content is served differently (A/B tests, consent pages replacing expected markup).

Related errors

AI-assisted analysis of ytdl-org/youtube-dl@956b8c5855 (2026-08-14). Data as JSON: /api/errors/d7499017734e06f6. Report an issue: GitHub.