pytest-dev/pytest · error · UsageError

: config option ' ' expects a list for type ' ', got

Error message

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

What it means

Raised by pytest's TOML config parser when an ini option declared as 'args' or 'linelist' is set to a non-list value. These types require a TOML array of strings. Like all TOML-mode validation, there is no implicit coercion from string or scalar.

Solutions

  1. Convert the value to a TOML inline array: change `addopts = "-v --tb=short"` to `addopts = ["-v", "--tb=short"]`
  2. For linelist types, each list element is one line — do not embed newlines in a single string
  3. Verify with tomllib that the value parses as a list of strings

Example fix

// pyproject.toml — before
[tool.pytest.ini_options]
addopts = "-v --tb=short"

// after
[tool.pytest.ini_options]
addopts = ["-v", "--tb=short"]
Defensive patterns

Strategy: validation

Validate before calling

import tomllib
with open('pyproject.toml', 'rb') as f:
    data = tomllib.load(f)
opts = data.get('tool', {}).get('pytest', {}).get('ini_options', {})
for key in ('addopts', 'filterwarnings', 'markers', 'norecursedirs'):
    if key in opts and not isinstance(opts[key], list):
        print(f"{key}: expected a TOML list, got {type(opts[key]).__name__}")

Type guard

def is_args_list(value: object) -> bool:
    return isinstance(value, list) and all(isinstance(item, str) for item in value)

Prevention

When it happens

Trigger: An addini(type='args') or addini(type='linelist') option is given a bare string or scalar in pyproject.toml instead of an inline array. Example: filterwarnings = "ignore" instead of filterwarnings = ["ignore"]. The `isinstance(value, list)` check in the `elif type in {"args", "linelist"}` branch fails.

Common situations: Treating a multi-value TOML option as a single string. Copying ini-style single-line values into TOML without array syntax. Expecting pytest to auto-split a comma-separated string (it does not in TOML mode).

Related errors

AI-assisted analysis of pytest-dev/pytest@0d6fbdeffa (2026-08-11). Data as JSON: /api/errors/199b710214e16b18. Report an issue: GitHub.

Appendix: 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 0d6fbdeffa)