yt-dlp/yt-dlp · error · ValueError

invalid {name} "{value}" given

Error message

invalid {name} "{value}" given

What it means

Default failure message of the validate() helper inside validate_options (yt_dlp/__init__.py). Any option check that fails without a custom message raises ValueError('invalid {name} "{value}" given'), where name is the human-readable option name (e.g. 'rate limit', 'buffer size'). Typical producers are validate_bytes (parse_bytes returned None for strings like "10Mbps") and validate_in/validate_regex fallbacks. The CLI catches this ValueError and aborts with a usage error before any download starts.

Source

Thrown at yt_dlp/__init__.py:189

        else:
            _unused_compat_opt('mtime-by-default')

    _video_multistreams_set = set_default_compat('multistreams', 'allow_multiple_video_streams', False, remove_compat=False)
    _audio_multistreams_set = set_default_compat('multistreams', 'allow_multiple_audio_streams', False, remove_compat=False)
    if _video_multistreams_set is False and _audio_multistreams_set is False:
        _unused_compat_opt('multistreams')
    if 'filename' in opts.compat_opts:
        if opts.outtmpl.get('default') is None:
            opts.outtmpl.update({'default': '%(title)s-%(id)s.%(ext)s'})
        else:
            _unused_compat_opt('filename')


def validate_options(opts):
    def validate(cndn, name, value=None, msg=None):
        if cndn:
            return True
        raise ValueError((msg or 'invalid {name} "{value}" given').format(name=name, value=value))

    def validate_in(name, value, items, msg=None):
        return validate(value is None or value in items, name, value, msg)

    def validate_regex(name, value, regex):
        return validate(value is None or re.match(regex, value), name, value)

    def validate_positive(name, value, strict=False):
        return validate(value is None or value > 0 or (not strict and value == 0),
                        name, value, '{name} "{value}" must be positive' + ('' if strict else ' or 0'))

    def validate_minmax(min_val, max_val, min_name, max_name=None):
        if max_val is None or min_val is None or max_val >= min_val:
            return
        if not max_name:
            min_name, max_name = f'min {min_name}', f'max {min_name}'
        raise ValueError(f'{max_name} "{max_val}" must be must be greater than or equal to {min_name} "{min_val}"')

View on GitHub (pinned to 81ecd58b13)

Solutions

1. Read the option name in the message and fix that exact value; sizes must be a plain number optionally followed by a unit like 10, 10M, 10MiB, 1.5G.
2. Check the option's accepted syntax with yt-dlp --help.
3. If the value comes from user input or config, validate it with yt_dlp.utils.parse_bytes (must not be None) before passing it on.
4. For programmatic opts, run yt_dlp.validate_options(opts) early so you get these errors at startup with your own handling.

Example fix

# before
ydl_opts = {'ratelimit': '10Mbps'}  # ValueError: invalid rate limit "10Mbps" given
# after
ydl_opts = {'ratelimit': '10M'}

from yt_dlp.utils import parse_bytes

for key in ('ratelimit', 'min_filesize', 'max_filesize', 'buffersize', 'http_chunk_size'):
    val = ydl_opts.get(key)
    if val is not None and parse_bytes(val) is None:
        raise SystemExit(f'invalid {key.replace("_", " ")} "{val}" given')

from yt_dlp import parse_options, validate_options
try:
    opts, urls = parse_options()
    validate_options(opts)
except ValueError as err:
    raise SystemExit(f'bad yt-dlp options: {err}')

When it happens

Trigger: Passing a non-numeric byte-size to --limit-rate, --min-filesize, --max-filesize, --buffer-size, or --http-chunk-size (parse_bytes must return a number; suffixes k/M/G/T/P/E/Z/Y and optional 'B'/'iB' are accepted); or an option value failing validate_in/validate_regex without a dedicated message. Programmatically: calling yt_dlp.validate_options(opts) on a hand-built opts object.

Common situations: Typing --limit-rate 10Mbps instead of 10M; --max-filesize 1GBs; passing empty strings or negative sizes; scripts assembling opts objects with unvalidated strings from config files or web forms.

Related errors

• {max_name} "{max_val}" must be must be greater than or equal
• invalid {key} retry sleep expression {expr!r}
• Invalid playlist-items {opts.playlist_items!r}: {err}
• "{policy}" is not a valid color policy
• invalid {msg} "{tmpl}": {err}

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