What causes "%s: %s" in ytdl-org/youtube-dl?

Read the chained cause text after the colon - it names the real failure (timeout, 403, DNS).

ytdl-org/youtube-dl · error · ExtractorError

%s: %s

Error message

%s: %s

What it means

This is ITVBaseIE's centralized wrapper around webpage-download failures: a '%s: %s' message pairing the errnote (default 'Unable to download webpage') with the underlying exception string. With fatal=True it re-raises as ExtractorError chaining the original cause; with fatal=False it degrades to a warning and returns False.

Source

Thrown at youtube_dl/extractor/itv.py:46

    smuggle_url,
    strip_or_none,
    traverse_obj,
    url_or_none,
    urljoin,
)


class ITVBaseIE(InfoExtractor):

    def __handle_request_webpage_error(self, err, video_id=None, errnote=None, fatal=True):
        if errnote is False:
            return False
        if errnote is None:
            errnote = 'Unable to download webpage'

        errmsg = '%s: %s' % (errnote, error_to_compat_str(err))
        if fatal:
            raise ExtractorError(errmsg, sys.exc_info()[2], cause=err, video_id=video_id)
        else:
            self._downloader.report_warning(errmsg)
            return False

    @staticmethod
    def _vanilla_ua_header():
        return {'User-Agent': 'Mozilla/5.0'}

    def _download_webpage_handle(self, url, video_id, *args, **kwargs):
        # specialised to (a) use vanilla UA (b) detect geo-block
        params = self._downloader.params
        nkwargs = {}
        if (
                'user_agent' not in params
                and not any(re.match(r'(?i)user-agent\s*:', h)
                            for h in (params.get('headers') or []))
                and 'User-Agent' not in (kwargs.get('headers') or {})):

View on GitHub (pinned to 956b8c5855)

Solutions

Read the chained cause text after the colon - it names the real failure (timeout, 403, DNS).
For geo errors, access ITV from a UK IP.
Retry for transient network/CDN failures.
Update youtube-dl/yt-dlp if ITV changed its page/geo flow.

Defensive patterns

Strategy: try-catch

Try / catch

try:
    ydl.extract_info(itv_url)
except ExtractorError as e:
    cause = e.cause
    msg = str(e)
    if 'Forbidden' in msg or '403' in msg or 'geo' in msg.lower():
        skip('likely UK-only')
    else:
        retry_with_backoff(itv_url)

Prevention

Inspect e.cause for the underlying urllib/HTTP error before deciding to retry.
Restrict ITV jobs to UK egress IPs.
Set sane socket timeouts and per-URL retry caps in downloader params.

When it happens

Trigger: _download_webpage_handle on itv.com URLs failing at the HTTP layer - timeouts, 4xx/5xx, TLS errors, or geo-block redirects - where the specialized ITV handler catches the request error and re-packages it.

Common situations: ITV Hub content requested from outside the UK (ITV geo-blocks aggressively), transient CDN errors, or ITV bot-detection refusing the vanilla 'Mozilla/5.0' user agent the extractor deliberately uses.

Related errors

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