pytest-dev/pytest · error · TypeError

{self.inipath}: config option '{name}' expects a list for ty

Error message

{self.inipath}: config option '{name}' expects a list for type '{type}', got {value_type}: {value!r}

What it means

Raised by Config._getini_toml (config/__init__.py:1978-1984) for options of type 'args' or 'linelist' in TOML mode when the supplied value is not a list. In TOML these types strictly require an array; a scalar string or other type is rejected, unlike INI mode where a string is split into tokens.

Source

Thrown at src/_pytest/config/__init__.py:1981

                    f"got {value_type}: {value!r}"
                )
            for i, item in enumerate(value):
                if not isinstance(item, str):
                    item_type = builtins.type(item).__name__
                    raise TypeError(
                        f"{self.inipath}: config option '{name}' expects a list of strings, "
                        f"but item at index {i} is {item_type}: {item!r}"
                    )
            dp = (
                self.inipath.parent
                if self.inipath is not None
                else self.invocation_params.dir
            )
            return [dp / x for x in value]
        elif type in {"args", "linelist"}:
            # Expect a list of strings.
            if not isinstance(value, list):
                raise TypeError(
                    f"{self.inipath}: config option '{name}' expects a list for type '{type}', "
                    f"got {value_type}: {value!r}"
                )
            for i, item in enumerate(value):
                if not isinstance(item, str):
                    item_type = builtins.type(item).__name__
                    raise TypeError(
                        f"{self.inipath}: config option '{name}' expects a list of strings, "
                        f"but item at index {i} is {item_type}: {item!r}"
                    )
            return list(value)
        elif type == "bool":
            # Expect a boolean.
            if not isinstance(value, bool):
                raise TypeError(
                    f"{self.inipath}: config option '{name}' expects a bool, "
                    f"got {value_type}: {value!r}"
                )

View on GitHub (pinned to 98b357f69e)

Solutions

Express the value as a TOML array of strings: addopts = ["-v", "--foo"].
For linelist, each array entry is one line — do not concatenate with newlines.
Confirm the registered type (args vs linelist) and follow that array convention.

Example fix

# before (pyproject.toml)
addopts = "-v --strict-markers"

# after
addopts = ["-v", "--strict-markers"]

Defensive patterns

Strategy: validation

Validate before calling

def ensure_list(value):
    if not isinstance(value, list):
        raise TypeError('args/linelist option must be a list in TOML mode')
    return value

Type guard

def is_str_list(value) -> bool:
    return isinstance(value, list) and all(isinstance(x, str) for x in value)

Try / catch

try:
    config.getini(name)
except Exception:
    # convert scalar to [scalar] in pyproject.toml and reload

Prevention

Express addopts/filterwarnings as TOML arrays of strings.
Do not paste INI single-line values verbatim into TOML.
Lint [tool.pytest.ini_options] in CI.

When it happens

Trigger: Setting an args/linelist option (e.g. addopts, filterwarnings, markers) in pyproject.toml to a bare scalar instead of an array.

Common situations: Writing addopts = '-v' (string) instead of addopts = ['-v'] (array) in pyproject.toml; porting from pytest.ini's `addopts = -v --foo` line directly into TOML.

Related errors

AI-assisted analysis of pytest-dev/pytest@98b357f69e (2026-08-04). Data as JSON: /data/errors/199b710214e16b18.json. Report an issue: GitHub.