pytest-dev/pytest · error · UsageError

{path}: {exc}

Error message

{path}: {exc}

What it means

pytest raises UsageError when a TOML config file (pyproject.toml or a pytest .toml config) contains syntax that tomllib/tomli cannot parse. The path and the underlying TOMLDecodeError detail are surfaced so the user can locate the malformed line.

Source

Thrown at src/_pytest/config/findpaths.py:73

    except iniconfig.ParseError as exc:
        raise UsageError(str(exc)) from exc


def _parse_toml_file(path: Path) -> dict[str, object]:
    """Parse the given '.toml' file, returning the decoded document.

    Raise UsageError if the file cannot be parsed.
    """
    if sys.version_info >= (3, 11):
        import tomllib
    else:
        import tomli as tomllib

    toml_text = path.read_text(encoding="utf-8")
    try:
        return tomllib.loads(toml_text)
    except tomllib.TOMLDecodeError as exc:
        raise UsageError(f"{path}: {exc}") from exc


def _load_pytest_ini(path: Path) -> ConfigDict | None:
    """Load a dedicated pytest INI file (``pytest.ini``/``.pytest.ini``).

    These files are always the source of configuration, even if they lack a
    ``[pytest]`` section, in which case an empty config is returned.
    """
    iniconfig = _parse_ini_config(path)

    if "pytest" in iniconfig:
        return {
            k: ConfigValue(v, origin="file", mode="ini")
            for k, v in iniconfig["pytest"].items()
        }
    return {}

View on GitHub (pinned to 0d6fbdeffa)

Solutions

1. Open the file at {path} and locate the line/column from the TOMLDecodeError detail, then fix the TOML syntax.
2. Validate the file with an external TOML linter or 'python -c "import tomllib; tomllib.loads(open(\"pyproject.toml\").read())"'.
3. If a recent merge left conflict markers (<<<, >>>), resolve them and re-save.

Example fix

// before
[tool.pytest.ini_options]
addopts = -ra
  -q   # invalid: continuation needs array form
// after
[tool.pytest.ini_options]
addopts = ["-ra", "-q"]

import tomllib, pathlib

def validate_toml(path: str) -> None:
    try:
        tomllib.loads(pathlib.Path(path).read_text(encoding='utf-8'))
    except tomllib.TOMLDecodeError as e:
        raise SystemExit(f'{path}: {e}') from e

null

null

When it happens

Trigger: Editing pyproject.toml and leaving an unquoted string, mismatched brackets, a duplicate key, or a stray character; saving with an editor that injected BOM or non-UTF-8 bytes; manual merge-conflict residue inside [tool.pytest.ini_options].

Common situations: Botched merge of pyproject.toml; copy-pasting a snippet that uses ' =' assignments invalid in TOML; trailing inline-table commas; non-ASCII paths without quotes.

Related errors

• {path}: pytest configuration must be under a [pytest] table
• {path}: Cannot use both [tool.pytest] (native TOML types) an
• {path}: Cannot use both [pytest] and [tool.pytest]/[tool.pyt
• {self.inipath}: config option '{name}' expects one of {_ini_
• {self.inipath}: config option '{name}' expects a string, got

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