ytdl-org/youtube-dl · error · ExtractorError

message

Error message

message

What it means

Raised by the Hotstar extractor when a call to Hotstar's API fails with an HTTP error whose JSON body contains a 'message' field, and that message is neither 'Content not available in region' / 'Country is not supported' (which become geo-restricted errors) nor a 402 (which triggers a login-required error). The raw server message is re-packed into a generic ExtractorError and shown to the user.

Source

Thrown at youtube_dl/extractor/hotstar.py:66

        if response['statusCode'] != 'OK':
            raise ExtractorError(
                response['body']['message'], expected=True)
        return response['body']['results']

    def _call_api_v2(self, path, video_id, headers, query=None, data=None):
        h = {'X-Request-Id': compat_str(uuid.uuid4())}
        h.update(headers)
        try:
            return self._call_api_impl(
                path, video_id, h, query, data)
        except ExtractorError as e:
            if isinstance(e.cause, compat_HTTPError):
                if e.cause.code == 402:
                    self.raise_login_required()
                message = self._parse_json(e.cause.read().decode(), video_id)['message']
                if message in ('Content not available in region', 'Country is not supported'):
                    raise self.raise_geo_restricted(message)
                raise ExtractorError(message)
            raise e


class HotStarIE(HotStarBaseIE):
    IE_NAME = 'hotstar'
    _VALID_URL = r'https?://(?:www\.)?hotstar\.com/(?:.+[/-])?(?P<id>\d{10})'
    _TESTS = [{
        # contentData
        'url': 'https://www.hotstar.com/can-you-not-spread-rumours/1000076273',
        'info_dict': {
            'id': '1000076273',
            'ext': 'mp4',
            'title': 'Can You Not Spread Rumours?',
            'description': 'md5:c957d8868e9bc793ccb813691cc4c434',
            'timestamp': 1447248600,
            'upload_date': '20151111',
            'duration': 381,
        },

View on GitHub (pinned to 956b8c5855)

Solutions

  1. Verify the Hotstar URL is still valid and the content is not expired or members-only (open it in a browser).
  2. Update to the latest youtube-dl / yt-dlp, since Hotstar's API changes frequently and the extractor is patched often.
  3. For premium content, supply credentials via the extractor's supported login mechanism so the 402 path can obtain a token.
  4. If the message indicates geo blocking in new wording, access via an allowed region and retry.

Example fix

// before
youtube_dl 'https://www.hotstar.com/some-show/1000076273'
# => ExtractorError: <server message>

// after
# confirm the URL in a browser; if it 404s or is DRM/paywalled, use a valid free URL
youtube_dl 'https://www.hotstar.com/can-you-not-spread-rumours/1000076273'
Defensive patterns

Strategy: try-catch

Try / catch

from youtube_dl.utils import ExtractorError
try:
    ydl.extract_info('https://www.hotstar.com/-/1000076273', download=False)
except ExtractorError as e:
    # server message is in str(e); treat non-geo API failures as fatal-for-this-url
    log.warning('hotstar rejected: %s', e)

Prevention

When it happens

Trigger: Any _call_api_impl request (e.g. 'um/v3/users' token creation, or content metadata 'o/v1/...' paths) that returns a non-2xx HTTP status with a JSON body whose 'message' is something other than the two known geo strings; e.g. 'Content is private', expired content IDs, or 'USER_TOKEN expired' style API errors.

Common situations: Removed/expired Hotstar content, premium content that needs a subscription cookie, API schema changes on Hotstar's side after the extractor was written, or regional CDN responses the extractor does not recognize.

Related errors

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