ytdl-org/youtube-dl · warning · ExtractorError

A network error has occurred.

Error message

A network error has occurred.

What it means

Raised by the generic extractor wrapper in InfoExtractor.extract when the underlying HTTP client raises http.client.IncompleteRead while an extractor is running: the server closed the connection before sending the full response body. It is wrapped as an expected ExtractorError with the original exception as cause, so callers can treat it as a transient network condition rather than a bug.

Source

Thrown at youtube_dl/extractor/common.py:585

    def extract(self, url):
        """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

View on GitHub (pinned to 956b8c5855)

Solutions

  1. Retry the extraction (optionally with --retries and --socket-timeout increased).
  2. Disable or change proxies/VPNs that may be truncating responses.
  3. If it is reproducible for one site only, the site's server/CDN is at fault — try later or from a different network.
  4. Update youtube-dl/yt-dlp; HTTP stack hardening (retries around IncompleteRead) improved over versions.

Example fix

from youtube_dl.utils import ExtractorError
import http.client

for attempt in range(3):
    try:
        info = ydl.extract_info(url, download=False)
        break
    except ExtractorError as e:
        if isinstance(e.cause, http.client.IncompleteRead) and attempt < 2:
            continue
        raise
Defensive patterns

Strategy: retry

Try / catch

from youtube_dl.utils import ExtractorError
import http.client
for attempt in range(3):
    try:
        info = ydl.extract_info(url, download=False)
        break
    except ExtractorError as e:
        if isinstance(e.cause, http.client.IncompleteRead) and attempt < 2:
            continue  # transient truncation; retry
        raise

Prevention

When it happens

Trigger: Any webpage/API download during _real_extract where the server (or a proxy/CDN in between) truncates the response — flaky connections, rate-limiting middleboxes that cut transfers, or servers closing keep-alive sockets early.

Common situations: Unstable Wi-Fi/VPN, aggressive CDN throttling on video sites, proxy interference, transient server faults. Re-running the same command often succeeds.

Related errors

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