pypa/pip · error · OptionError

Value for option {} must be one of {}

Error message

Value for option {} must be one of {}

What it means

Pygments' get_choice_opt raises OptionError when an option's value is not a member of the explicitly allowed set. It is used to validate enumerated/choice options passed in a lexer or formatter options dictionary, producing a message that lists both the option name and the allowed values.

Source

Thrown at src/pip/_vendor/pygments/util.py:49

    """Raised if one of the lookup functions didn't find a matching class."""


class OptionError(Exception):
    """
    This exception will be raised by all option processing functions if
    the type or value of the argument is not correct.
    """

def get_choice_opt(options, optname, allowed, default=None, normcase=False):
    """
    If the key `optname` from the dictionary is not in the sequence
    `allowed`, raise an error, otherwise return it.
    """
    string = options.get(optname, default)
    if normcase:
        string = string.lower()
    if string not in allowed:
        raise OptionError('Value for option {} must be one of {}'.format(optname, ', '.join(map(str, allowed))))
    return string


def get_bool_opt(options, optname, default=None):
    """
    Intuitively, this is `options.get(optname, default)`, but restricted to
    Boolean value. The Booleans can be represented as string, in order to accept
    Boolean value from the command line arguments. If the key `optname` is
    present in the dictionary `options` and is not associated with a Boolean,
    raise an `OptionError`. If it is absent, `default` is returned instead.

    The valid string values for ``True`` are ``1``, ``yes``, ``true`` and
    ``on``, the ones for ``False`` are ``0``, ``no``, ``false`` and ``off``
    (matched case-insensitively).
    """
    string = options.get(optname, default)
    if isinstance(string, bool):
        return string

View on GitHub (pinned to d7d0d0a394)

Solutions

1. Check the error message's allowed list and set options[optname] to one of those exact values.
2. If a default is acceptable, omit the key so get_choice_opt falls back to the provided default.
3. Validate the value against the allowed set before constructing the formatter/lexer.

Example fix

# before
opt = get_choice_opt(opts, 'encoding', ['utf-8', 'latin1'])  # opts['encoding']='ascii'

# after
opts['encoding'] = 'utf-8'
opt = get_choice_opt(opts, 'encoding', ['utf-8', 'latin1'])

ALLOWED = ('utf-8', 'latin1')
if opts.get('encoding') not in ALLOWED:
    raise ValueError(f"encoding must be one of {ALLOWED}")
get_choice_opt(opts, 'encoding', ALLOWED)

from pip._vendor.pygments.util import OptionError
try:
    val = get_choice_opt(opts, 'encoding', ['utf-8', 'latin1'])
except OptionError as e:
    opts['encoding'] = 'utf-8'
    val = 'utf-8'

When it happens

Trigger: Calling get_choice_opt(options, optname, allowed) where options[optname] is a value not contained in the allowed sequence; for example passing style_name='native' to an option whose allowed set excludes it, or a formatter/lexer that forwards a user-supplied config dict to get_choice_opt.

Common situations: Passing an invalid string to a choice-style config key; a typo in an enumerated value read from a config file or CLI; version upgrades that rename or remove a previously-valid choice.

Related errors

• Invalid type {string!r} for option {optname}; use 1/0, yes/n
• Invalid value {string!r} for option {optname}; use 1/0, yes/
• Invalid type {string!r} for option {optname}; you must give
• Invalid value {string!r} for option {optname}; you must give
• Invalid type {val!r} for option {optname}; you must give a l

AI-assisted analysis of pypa/pip@d7d0d0a394 (2026-08-04). Data as JSON: /data/errors/349b234bfb0ad324.json. Report an issue: GitHub.