{"record":{"id":"595029bb5a6583ce","repo":"yt-dlp/yt-dlp","slug":"policy-is-not-a-valid-color-policy","errorCode":null,"errorMessage":"\"{policy}\" is not a valid color policy","messagePattern":"\"(.+?)\" is not a valid color policy","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"yt_dlp/__init__.py","lineNumber":498,"sourceCode":"        opts.headers.setdefault('Referer', opts.referer)\n\n    if opts.no_sponsorblock:\n        opts.sponsorblock_mark = opts.sponsorblock_remove = set()\n\n    default_downloader = None\n    for proto, path in opts.external_downloader.items():\n        if path == 'native':\n            continue\n        ed = get_external_downloader(path)\n        if ed is None:\n            raise ValueError(\n                f'No such {format_field(proto, None, \"%s \", ignore=\"default\")}external downloader \"{path}\"')\n        elif ed and proto == 'default':\n            default_downloader = ed.get_basename()\n\n    for policy in opts.color.values():\n        if policy not in ('always', 'auto', 'auto-tty', 'no_color', 'no_color-tty', 'never'):\n            raise ValueError(f'\"{policy}\" is not a valid color policy')\n\n    warnings, deprecation_warnings = [], []\n\n    # Common mistake: -f best\n    if opts.format == 'best':\n        warnings.append('.\\n         '.join((\n            '\"-f best\" selects the best pre-merged format which is often not the best option',\n            'To let yt-dlp download and merge the best available formats, simply do not pass any format selection',\n            'If you know what you are doing and want only the best pre-merged format, use \"-f b\" instead to suppress this warning')))\n\n    # Common mistake: -f mp4\n    if opts.format == 'mp4':\n        warnings.append('.\\n         '.join((\n            '\"-f mp4\" selects the best pre-merged mp4 format which is often not what\\'s intended',\n            'Pre-merged mp4 formats are not available from all sites, or may only be available in lower quality',\n            'To prioritize the best h264 video and aac audio in an mp4 container, use \"-t mp4\" instead',\n            'If you know what you are doing and want a pre-merged mp4 format, use \"-f b[ext=mp4]\" instead to suppress this warning')))\n","sourceCodeStart":480,"sourceCodeEnd":516,"githubUrl":"https://github.com/yt-dlp/yt-dlp/blob/81ecd58b1394793e6da9998cc19fdb45657f1685/yt_dlp/__init__.py#L480-L516","documentation":"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.","triggerScenarios":"--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.","commonSituations":"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.","solutions":["Use one of: always, auto, auto-tty, no_color, no_color-tty, never.","For 'no color at all' use --color never.","Check yt-dlp --help | grep -A3 -- --color for the exact list in your version."],"exampleFix":"# before\nyt-dlp --color=always-tty URL\n# ValueError: \"always-tty\" is not a valid color policy\n\n# after\nyt-dlp --color=always URL   # or auto, auto-tty, no_color, no_color-tty, never","handlingStrategy":"validation","validationCode":"VALID_COLOR_POLICIES = ('always', 'auto', 'auto-tty', 'no_color', 'no_color-tty', 'never')\n\nfor stream_policy in color_policies:  # anything sourced from user/config\n    if stream_policy not in VALID_COLOR_POLICIES:\n        raise SystemExit(f'\"{stream_policy}\" is not a valid color policy')","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Copy policy names exactly — underscores in no_color, hyphens in auto-tty.","Use --color never to disable color outright.","Source policies from a validated list in config tooling, never free text."],"tags":["cli","color","options","validation","terminal"],"backgroundTag":"invalid-color-policy","analyzedSha":"81ecd58b1394793e6da9998cc19fdb45657f1685","analyzedAt":"2026-08-22T12:21:25.439Z","schemaVersion":2},"datasetVersion":"2026-08-22T14:17:55.899Z"}