ytdl-org/youtube-dl · error · ExtractorError

%s returned error: %s - %s

Error message

%s returned error: %s - %s

What it means

Raised by MTV's _get_video_info when the downloaded mediagen XML contains a <item type="text"> element — the API's way of returning a textual error instead of video data. The message assembles the IE name, optional item code attribute, and the item's text. It is expected=True.

Source

Thrown at youtube_dl/extractor/mtv.py:156

        mediagen_url = mediagen_url.replace('device={device}', '')
        if 'acceptMethods' not in mediagen_url:
            mediagen_url += '&' if '?' in mediagen_url else '?'
            mediagen_url += 'acceptMethods='
            mediagen_url += 'hls' if use_hls else 'fms'

        mediagen_doc = self._download_xml(
            mediagen_url, video_id, 'Downloading video urls', fatal=False)

        if mediagen_doc is False:
            return None

        item = mediagen_doc.find('./video/item')
        if item is not None and item.get('type') == 'text':
            message = '%s returned error: ' % self.IE_NAME
            if item.get('code') is not None:
                message += '%s - ' % item.get('code')
            message += item.text
            raise ExtractorError(message, expected=True)

        description = strip_or_none(xpath_text(itemdoc, 'description'))

        timestamp = timeconvert(xpath_text(itemdoc, 'pubDate'))

        title_el = None
        if title_el is None:
            title_el = find_xpath_attr(
                itemdoc, './/{http://search.yahoo.com/mrss/}category',
                'scheme', 'urn:mtvn:video_title')
        if title_el is None:
            title_el = itemdoc.find(compat_xpath('.//{http://search.yahoo.com/mrss/}title'))
        if title_el is None:
            title_el = itemdoc.find(compat_xpath('.//title'))
            if title_el.text is None:
                title_el = None

        title = title_el.text

View on GitHub (pinned to 956b8c5855)

Solutions

1. Read the returned code/text — it states the site's reason (expired, region, rights) and whether a proxy would help.
2. If the code suggests geo restriction, retry with --geo-verify-proxy or a US proxy.
3. Update youtube-dl; GUID/mediagen changes are handled over time in the extractor.
4. Confirm the video still plays in a browser; if not, the link is dead.

Example fix

youtube-dl --geo-verify-proxy '<url>'   # else: pip install -U youtube-dl

except ExtractorError as e:
    if e.expected and 'returned error' in str(e):
        handle_mtv_error(url, str(e))  # parse optional 'code - text' payload
    else:
        raise

When it happens

Trigger: Any MTV-family extraction whose mediagen response has ./video/item with type='text'; the 'code' attribute is appended when present, followed by the free-text error body.

Common situations: Expired/removed MTV videos; content unavailable for the requesting region; the GUID from the page no longer resolving in mediagen after a site migration — fixed only by an extractor update.

Related errors

• %s said: %s
• This video is not available from your country.
• %s said: video is not available
• %s: No songs found, try using proxy
• %s (site code %d)

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