yt-dlp/yt-dlp · error · ExtractorError

Invalid format sort string "{item}" given by extractor

Error message

Invalid format sort string "{item}" given by extractor

What it means

Raised inside FormatSorter when a format-sort item supplied by an extractor (the 'format_sort' field of the info dict, collected as sort_extractor) fails to match the sort-item regex. Every item in the composed sort_list is validated with re.match(self.regex, item); a non-matching string raises ExtractorError('Invalid format sort string "<item>" given by extractor'). Items must be a known field, optionally prefixed with +/- and with an optional :limit or ~separator.

Source

Thrown at yt_dlp/utils/_utils.py:5537

                'reverse': reverse,
                'closest': False if limit is None else closest,
                'limit_text': limit_text,
                'limit': limit}
            if field in self.settings:
                self.settings[field].update(data)
            else:
                self.settings[field] = data

        sort_list = (
            tuple(field for field in self.default if self._get_field_setting(field, 'forced'))
            + (tuple() if params.get('format_sort_force', False)
                else tuple(field for field in self.default if self._get_field_setting(field, 'priority')))
            + tuple(self._sort_user) + tuple(sort_extractor) + self.default)

        for item in sort_list:
            match = re.match(self.regex, item)
            if match is None:
                raise ExtractorError(f'Invalid format sort string "{item}" given by extractor')
            field = match.group('field')
            if field is None:
                continue
            if self._get_field_setting(field, 'type') == 'alias':
                alias, field = field, self._get_field_setting(field, 'field')
                if self._get_field_setting(alias, 'deprecated'):
                    self.ydl.deprecated_feature(f'Format sorting alias {alias} is deprecated and may '
                                                f'be removed in a future version. Please use {field} instead')
            reverse = match.group('reverse') is not None
            closest = match.group('separator') == '~'
            limit_text = match.group('limit')

            has_limit = limit_text is not None
            has_multiple_fields = self._get_field_setting(field, 'type') == 'combined'
            has_multiple_limits = has_limit and has_multiple_fields and not self._get_field_setting(field, 'same_limit')

            fields = self._get_field_setting(field, 'field') if has_multiple_fields else (field,)
            limits = limit_text.split(':') if has_multiple_limits else (limit_text,) if has_limit else tuple()

View on GitHub (pinned to 81ecd58b13)

Solutions

1. Update yt-dlp - if a built-in extractor emits a bad string this is a bug and gets patched
2. If you use plugin extractors, update or disable the plugin whose extractor sets format_sort
3. If you maintain the extractor, emit only valid items: field names from FormatSorter (lang, vcodec, acodec, size, tbr, proto, ext, ...) with optional leading +/-, optional ~closest marker and :limit, e.g. '+vcodec:h264' or 'res~720'
4. Report with yt-dlp -v output including the offending item so it can be reproduced

Example fix

# before (extractor code)
'format_sort': ['vcodec:'],  # ExtractorError: Invalid format sort string "vcodec:" given by extractor

# after
'format_sort': ['+vcodec', 'res'],

from yt_dlp.utils import FormatSorter
sort_re = FormatSorter(None).regex  # reuse the exact validation regex

def valid_sort_item(item: str) -> bool:
    return sort_re.match(item) is not None

# as an yt-dlp user you cannot fix extractor-supplied sort strings;
# catch and continue with other videos
from yt_dlp.utils import ExtractorError
try:
    ydl.download([url])
except ExtractorError as e:
    if 'Invalid format sort string' in str(e):
        logger.error('extractor bug for %s; update yt-dlp', url)

When it happens

Trigger: A built-in or plugin extractor puts a malformed string (e.g. 'vcodec:', 'proto;', 'quality+') into info['format_sort']; or a yt-dlp version where the field name a plugin uses is not in FormatSorter's field list.

Common situations: Third-party/forked extractor plugins that set format_sort without validating; running an outdated yt-dlp whose field set differs from what the extractor expects; hand-edited forks after a FormatSorter refactor.

Related errors

• Missing netrc_machine and {type(self).__name__}._NETRC_MACHI
• Unsafe placeholder for exec command: {na!r} The --output-na-
• Unsafe default(s) in exec command: {outtmpl!r} Conversions a
• Invalid syntax in Cookie Header
• Wrong regex for subtitlelangs: {e.pattern}

AI-assisted analysis of yt-dlp/yt-dlp@81ecd58b13 (2026-08-22). Data as JSON: /api/errors/52bbd06eac8a97b9. Report an issue: GitHub.