ytdl-org/youtube-dl · error · ExtractorError

error

Error message

error

What it means

Raised by the RTHK (HKTVE/hketv) extractor when the API response lacks success or access; the message is the cleaned access_err_msg text. If that text contains 'Video streaming is not available in your country' it raises geo-restricted instead. Marked expected=True.

Source

Thrown at youtube_dl/extractor/hketv.py:117

            'video_url': file_id,
        }

        response = self._download_json(
            self._APPS_BASE_URL + '/media/play/handler.php', video_id,
            data=urlencode_postdata(data),
            headers=merge_dicts({
                'Content-Type': 'application/x-www-form-urlencoded'},
                self.geo_verification_headers()))

        result = response['result']

        if not response.get('success') or not response.get('access'):
            error = clean_html(response.get('access_err_msg'))
            if 'Video streaming is not available in your country' in error:
                self.raise_geo_restricted(
                    msg=error, countries=self._GEO_COUNTRIES)
            else:
                raise ExtractorError(error, expected=True)

        formats = []

        width = int_or_none(result.get('width'))
        height = int_or_none(result.get('height'))

        playlist0 = result['playlist'][0]
        for fmt in playlist0['sources']:
            file_url = urljoin(self._APPS_BASE_URL, fmt.get('file'))
            if not file_url:
                continue
            # If we ever wanted to provide the final resolved URL that
            # does not require cookies, albeit with a shorter lifespan:
            #     urlh = self._downloader.urlopen(file_url)
            #     resolved_url = urlh.geturl()
            label = fmt.get('label')
            h = self._FORMAT_HEIGHTS.get(label)
            w = h * width // height if h and width and height else None

View on GitHub (pinned to 956b8c5855)

Solutions

  1. If geo-related, use an HK IP or pass --geo-verification-proxy
  2. Confirm the programme still plays at hketv.com / rthk.hk in a browser
  3. Update youtube-dl/yt-dlp for API changes
  4. Run with -v to read the exact access_err_msg
Defensive patterns

Strategy: try-catch

Validate before calling

import requests
resp = requests.post(HKETV_API, data=payload, headers={'Content-Type': 'application/x-www-form-urlencoded'}).json()
if not resp.get('success') or not resp.get('access'):
    print('HKETV refusal:', resp.get('access_err_msg'))

Type guard

def hketv_accessible(response):
    return bool(response.get('success')) and bool(response.get('access')) and response.get('result', {}).get('playlist')

Try / catch

try:
    ydl.extract_info(url)
except DownloadError as e:
    if 'not available in your country' in str(e):
        use_geo_proxy_and_retry(url)
    elif 'HKETV' in str(e):
        skip_as_unavailable(url)
    else:
        raise

Prevention

When it happens

Trigger: POSTing to the hketv API where response.success/access is false: accessing RTHK content outside allowed regions without geo bypass, or the specific programme being unpublished/expired.

Common situations: Non-HK IP hitting region-locked RTHK programmes (message variant without the exact country string), removed programmes, or API payload changes in old youtube-dl builds.

Related errors

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