pypa/pip · error · OptionError

Invalid type {val!r} for option {optname}; you must give a l

Error message

Invalid type {val!r} for option {optname}; you must give a list value

What it means

Pygments' get_list_opt raises OptionError when the option value is neither a string (which would be whitespace-split) nor a list/tuple. Any other type (None, int, dict) is rejected because it cannot be interpreted as a list.

Source

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

        raise OptionError(f'Invalid type {string!r} for option {optname}; you '
                          'must give an integer value')
    except ValueError:
        raise OptionError(f'Invalid value {string!r} for option {optname}; you '
                          'must give an integer value')

def get_list_opt(options, optname, default=None):
    """
    If the key `optname` from the dictionary `options` is a string,
    split it at whitespace and return it. If it is already a list
    or a tuple, it is returned as a list.
    """
    val = options.get(optname, default)
    if isinstance(val, str):
        return val.split()
    elif isinstance(val, (list, tuple)):
        return list(val)
    else:
        raise OptionError(f'Invalid type {val!r} for option {optname}; you '
                          'must give a list value')


def docstring_headline(obj):
    if not obj.__doc__:
        return ''
    res = []
    for line in obj.__doc__.strip().splitlines():
        if line.strip():
            res.append(" " + line.strip())
        else:
            break
    return ''.join(res).lstrip()


def make_analysator(f):
    """Return a static text analyser function that returns float values."""
    def text_analyse(text):

View on GitHub (pinned to d7d0d0a394)

Solutions

Pass the value as a string (split on whitespace) or as a list/tuple.
Provide a default list when the key may be absent.
Normalize the config source so the key always yields a list.

Example fix

# before
opts['filenames'] = None
val = get_list_opt(opts, 'filenames')

# after
opts['filenames'] = '*.txt *.md'
val = get_list_opt(opts, 'filenames')

Defensive patterns

Strategy: type-guard

Validate before calling

v = opts.get('filenames')
if not isinstance(v, (str, list, tuple)):
    opts['filenames'] = []

Type guard

def is_list_option_value(v) -> bool:
    return isinstance(v, (str, list, tuple))

Try / catch

from pip._vendor.pygments.util import OptionError
try:
    val = get_list_opt(opts, 'filenames', default=[])
except OptionError:
    val = []

Prevention

Provide a list default for optional list keys.
Wrap single scalar values in a list at the config boundary.

When it happens

Trigger: Calling get_list_opt(options, optname) where options[optname] is None (and no default), an int, or a dict; the function only accepts str, list, or tuple.

Common situations: A missing list option defaulted to None; a scalar accidentally supplied where a list was expected; JSON config yielding null or a number for what should be a list field.

Related errors

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