pytest-dev/pytest · error · UsageError

: config option ' ' expects a bool, got

Error message

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

What it means

Raised by pytest's TOML config parser when a 'bool'-type ini option receives a non-boolean value. TOML mode requires a literal true or false; it does not coerce strings like "yes"/"no"/"1"/"0". The error reports the actual type and value.

Solutions

  1. Use unquoted TOML booleans: change `addopts_verbose = "true"` to `addopts_verbose = true`
  2. Replace 0/1 with false/true respectively
  3. If the value comes from a variable or inline table, ensure the expression evaluates to a TOML bool

Example fix

// pyproject.toml — before
[tool.pytest.ini_options]
addopts_verbose = "true"

// after
[tool.pytest.ini_options]
addopts_verbose = true
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, val in opts.items():
    # Heuristic: option names likely to be bool
    if isinstance(val, str) and val.lower() in ('true', 'false', 'yes', 'no', '1', '0'):
        print(f"{key}: looks like an unquoted bool — got string {val!r}, consider {val.lower()}")

Type guard

def is_toml_bool(value: object) -> bool:
    # In TOML, booleans are native Python bool after parsing
    return isinstance(value, bool)

Prevention

When it happens

Trigger: An addini(type='bool') option is set to a string, integer, or other non-bool in pyproject.toml. Example: addopts_verbose = "true" (a string) or addopts_verbose = 1 (an int) instead of addopts_verbose = true (a TOML boolean). The `isinstance(value, bool)` check fails.

Common situations: Quoting a boolean (making it a string). Using 0/1 integers instead of true/false. Copying ini-style values where string "true" was accepted. Forgetting TOML booleans are unquoted lowercase keywords.

Related errors

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

Appendix: source

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

        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}"
                )
            return value
        elif type == "int":
            # Expect an integer (but not bool, which is a subclass of int).
            if not isinstance(value, int) or isinstance(value, bool):
                raise TypeError(
                    f"{self.inipath}: config option '{name}' expects an int, "
                    f"got {value_type}: {value!r}"
                )
            return value
        elif type == "float":
            # Expect a float or integer only.
            if not isinstance(value, (float, int)) or isinstance(value, bool):
                raise TypeError(
                    f"{self.inipath}: config option '{name}' expects a float, "
                    f"got {value_type}: {value!r}"

View on GitHub (pinned to 0d6fbdeffa)