yt-dlp/yt-dlp · error

"{policy}" is not a valid color policy

Error message

"{policy}" is not a valid color policy

What it means

Raised in validate_options when any entry of opts.color (the per-stream color policy mapping filled by --color) is not one of the six accepted policies: always, auto, auto-tty, no_color, no_color-tty, never. The check iterates every value in the dict, so a single bad policy anywhere rejects the run before any output is produced.

Source

Thrown at yt_dlp/__init__.py:498

        opts.headers.setdefault('Referer', opts.referer)

    if opts.no_sponsorblock:
        opts.sponsorblock_mark = opts.sponsorblock_remove = set()

    default_downloader = None
    for proto, path in opts.external_downloader.items():
        if path == 'native':
            continue
        ed = get_external_downloader(path)
        if ed is None:
            raise ValueError(
                f'No such {format_field(proto, None, "%s ", ignore="default")}external downloader "{path}"')
        elif ed and proto == 'default':
            default_downloader = ed.get_basename()

    for policy in opts.color.values():
        if policy not in ('always', 'auto', 'auto-tty', 'no_color', 'no_color-tty', 'never'):
            raise ValueError(f'"{policy}" is not a valid color policy')

    warnings, deprecation_warnings = [], []

    # Common mistake: -f best
    if opts.format == 'best':
        warnings.append('.\n         '.join((
            '"-f best" selects the best pre-merged format which is often not the best option',
            'To let yt-dlp download and merge the best available formats, simply do not pass any format selection',
            'If you know what you are doing and want only the best pre-merged format, use "-f b" instead to suppress this warning')))

    # Common mistake: -f mp4
    if opts.format == 'mp4':
        warnings.append('.\n         '.join((
            '"-f mp4" selects the best pre-merged mp4 format which is often not what\'s intended',
            'Pre-merged mp4 formats are not available from all sites, or may only be available in lower quality',
            'To prioritize the best h264 video and aac audio in an mp4 container, use "-t mp4" instead',
            'If you know what you are doing and want a pre-merged mp4 format, use "-f b[ext=mp4]" instead to suppress this warning')))

View on GitHub (pinned to 81ecd58b13)

Solutions

1. Use one of: always, auto, auto-tty, no_color, no_color-tty, never.
2. For 'no color at all' use --color never.
3. Check yt-dlp --help | grep -A3 -- --color for the exact list in your version.

Example fix

# before
yt-dlp --color=always-tty URL
# ValueError: "always-tty" is not a valid color policy

# after
yt-dlp --color=always URL   # or auto, auto-tty, no_color, no_color-tty, never

VALID_COLOR_POLICIES = ('always', 'auto', 'auto-tty', 'no_color', 'no_color-tty', 'never')

for stream_policy in color_policies:  # anything sourced from user/config
    if stream_policy not in VALID_COLOR_POLICIES:
        raise SystemExit(f'"{stream_policy}" is not a valid color policy')

When it happens

Trigger: --color always-tty (not a policy); --color no-color (hyphen vs underscore); typo'd 'alway'; combining unsupported streams/policies in one --color argument. API users building YoutubeDL with a plain params dict cannot hit this — it validates CLI-parsed opts only.

Common situations: Guessing policy names instead of checking --help; scripts forcing color in CI with '--color=always-tty'; mixing up no_color (the underscore policy) with terminal conventions like NO_COLOR.

Related errors

• invalid {name} "{value}" given
• {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}
• invalid {msg} "{tmpl}": {err}

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