ytdl-org/youtube-dl · error · ExtractorError

%s returned error: %s

Error message

%s returned error: %s

What it means

Raised inside FranceTV's _extract_video when the getInfosOeuvre/v2 API responds with status 'NOK'. The API's own 'message' field is surfaced, prefixed with the extractor name, as an expected error. status NOK is France Télévisions' way of saying the idDiffusion is unknown, delisted, or not served by the catalogue.

Source

Thrown at youtube_dl/extractor/francetv.py:101

    }, {
        # france-3 live
        'url': 'francetv:SIM_France3',
        'only_matching': True,
    }]

    def _extract_video(self, video_id, catalogue=None):
        # Videos are identified by idDiffusion so catalogue part is optional.
        # However when provided, some extra formats may be returned so we pass
        # it if available.
        info = self._download_json(
            'https://sivideo.webservices.francetelevisions.fr/tools/getInfosOeuvre/v2/',
            video_id, 'Downloading video JSON', query={
                'idDiffusion': video_id,
                'catalogue': catalogue or '',
            })

        if info.get('status') == 'NOK':
            raise ExtractorError(
                '%s returned error: %s' % (self.IE_NAME, info['message']),
                expected=True)
        allowed_countries = info['videos'][0].get('geoblocage')
        if allowed_countries:
            georestricted = True
            geo_info = self._download_json(
                'http://geo.francetv.fr/ws/edgescape.json', video_id,
                'Downloading geo restriction info')
            country = geo_info['reponse']['geo_info']['country_code']
            if country not in allowed_countries:
                raise ExtractorError(
                    'The video is not available from your location',
                    expected=True)
        else:
            georestricted = False

        def sign(manifest_url, manifest_id):
            for host in ('hdfauthftv-a.akamaihd.net', 'hdfauth.francetv.fr'):

View on GitHub (pinned to 956b8c5855)

Solutions

  1. Search the show on france.tv and copy the current URL — replays often move to new ids
  2. Double-check the idDiffusion value for typos/truncation
  3. Accept that French broadcasting rights typically expire replays after 7-30 days; no client fix exists for delisted content
  4. Update youtube-dl/yt-dlp if the API contract changed

Example fix

# before
youtube_dl 'https://www.france.tv/france-2/jt/old-expired-replay.html'
# ERROR: FranceTV returned error: ...

# after
yt-dlp 'https://www.france.tv/france-2/jt/current-available-episode.html'
Defensive patterns

Strategy: try-catch

Try / catch

try:
    info = ydl.extract_info(url)
except ExtractorError as e:
    if 'FranceTV returned error:' in str(e):
        mark_expired(url)  # NOK is usually permanent delisting

Prevention

When it happens

Trigger: The POST/GET to sivideo.webservices.francetelevisions.fr returns JSON with status == 'NOK'. Produced by a malformed idDiffusion UUID, a video removed from the francetv catalogue, or passing a catalogue value that does not match the video.

Common situations: Deep links from news articles to expired replays; France TV purging replays after rights expire; copy-paste errors in the idDiffusion parameter of pluton or direct francetv URLs.

Related errors

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