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 'paths', got {value_type}: {value!r}

What it means

Raised by Config._getini_toml (config/__init__.py:1958-1964) for a 'paths'-typed option in TOML mode when the value is not a Python list. paths in TOML must be an array of strings (each resolved relative to inipath); scalars or dicts are rejected with the actual type name embedded in the message.

Source

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

    def _getini_toml(
        self,
        name: str,
        canonical_name: str,
        type: str,
        value: object,
        default: Any,
    ):
        """Handle TOML config values with strict type validation and no coercion.

        In TOML mode, values already have native types from TOML parsing.
        We validate types match expectations exactly, including list items.
        """
        value_type = builtins.type(value).__name__
        if type == "paths":
            # Expect a list of strings.
            if not isinstance(value, list):
                raise TypeError(
                    f"{self.inipath}: config option '{name}' expects a list for type 'paths', "
                    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.

View on GitHub (pinned to 98b357f69e)

Solutions

Wrap the value in a TOML array: testpaths = ["tests", "integration"].
Confirm the option's registered type is 'paths' (it expects path-like strings as a list in TOML).
If you need the .ini single-string shorthand, keep the setting in pytest.ini instead.

Example fix

# before (pyproject.toml)
[tool.pytest.ini_options]
testpaths = "tests"

# after
testpaths = ["tests"]

Defensive patterns

Strategy: validation

Validate before calling

def ensure_paths_list(value):
    if not isinstance(value, list):
        raise TypeError('paths option must be a list in TOML mode')
    return value

Type guard

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

Try / catch

try:
    config.getini(name)
except Exception:
    # wrap the scalar in a list in pyproject.toml and reload

Prevention

Always express TOML paths as arrays of strings.
When migrating from .ini, wrap single strings in [] for paths options.
Lint pyproject.toml pytest sections in CI.

When it happens

Trigger: Setting a paths-typed ini option in pyproject.toml to a scalar string or anything other than a TOML array, e.g. testpaths = "tests" instead of testpaths = ["tests"].

Common situations: Migrating testpaths/norecursedirs/pythonpath/etc. from .ini (where a bare string is accepted and shlex-split) to pyproject.toml without wrapping in an array; misunderstanding TOML's stricter typing for paths.

Related errors

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