pytest-dev/pytest · error · UsageError

: config option ' ' expects an int, got

Error message

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

What it means

Raised by pytest's TOML config parser when an 'int'-type ini option receives a non-integer value, including a boolean. Because bool is a subclass of int in Python, the check explicitly rejects bools via `isinstance(value, bool)`. Floats and strings are also rejected.

Solutions

Use an unquoted integer: change `verbosity = "2"` to `verbosity = 2`
Remove decimal points: change `verbosity = 2.0` to `verbosity = 2`
Replace true/false with the intended integer (e.g., 1/0)

Example fix

// pyproject.toml — before
[tool.pytest.ini_options]
verbosity = "2"

// after
[tool.pytest.ini_options]
verbosity = 2

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():
    if isinstance(val, bool):
        print(f"{key}: got TOML bool, but type may expect int")
    elif isinstance(val, str):
        print(f"{key}: got string {val!r}, consider unquoted int if type is 'int'")
    elif isinstance(val, float):
        print(f"{key}: got float {val}, consider int if type is 'int'")

Type guard

def is_toml_int_strict(value: object) -> bool:
    return isinstance(value, int) and not isinstance(value, bool)

Prevention

Use unquoted integer literals for int options
Never quote integers or use decimal points for int options
Remember TOML true/false are bools, not ints — pytest rejects them for int options

When it happens

Trigger: An addini(type='int') option is set to a float, string, or bool in pyproject.toml. Example: verbosity = "2" (string) or verbosity = 2.0 (float) or verbosity = true (bool) instead of verbosity = 2 (integer). The check `not isinstance(value, int) or isinstance(value, bool)` triggers.

Common situations: Quoting an integer (making it a string). Using a float literal where an int is expected. Accidentally writing true/false (bool) for a numeric option. Confusing TOML number typing.

Related errors

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

Appendix: source

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

                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}"
                )
            return value
        elif type == "string":
            # Expect a string.
            if not isinstance(value, str):
                raise TypeError(
                    f"{self.inipath}: config option '{name}' expects a string, "
                    f"got {value_type}: {value!r}"

View on GitHub (pinned to 0d6fbdeffa)