pytest-dev/pytest · error · ValueError

unknown configuration value: {name!r}

Error message

unknown configuration value: {name!r}

What it means

Raised by Config._getini (config/__init__.py:1799-1806) when getini(name) is called for an option that was never registered via parser.addini during pytest_addoption. The lookup against _parser._inidict raises KeyError, which is converted to a ValueError naming the offending option.

Source

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

        self._inicache[canonical_name] = val = self._getini(canonical_name)
        return val

    # Meant for easy monkeypatching by legacypath plugin.
    # Can be inlined back (with no cover removed) once legacypath is gone.
    def _getini_unknown_type(self, name: str, type: str, value: object):
        msg = (
            f"Option {name} has unknown configuration type {type} with value {value!r}"
        )
        raise ValueError(msg)  # pragma: no cover

    def _getini(self, name: str):
        # If this is an alias, resolve to canonical name.
        canonical_name = self._parser._ini_aliases.get(name, name)

        try:
            _description, type, default = self._parser._inidict[canonical_name]
        except KeyError as e:
            raise ValueError(f"unknown configuration value: {name!r}") from e

        # Collect all possible values (canonical name + aliases) from _inicfg.
        # Each candidate is (ConfigValue, is_canonical).
        candidates = []
        if canonical_name in self._inicfg:
            candidates.append((self._inicfg[canonical_name], True))
        for alias, target in self._parser._ini_aliases.items():
            if target == canonical_name and alias in self._inicfg:
                candidates.append((self._inicfg[alias], False))

        if not candidates:
            return default

        # Pick the best candidate based on precedence:
        # 1. CLI override takes precedence over file, then
        # 2. Canonical name takes precedence over alias.
        selected = max(candidates, key=lambda x: (x[0].origin == "override", x[1]))[0]
        value = selected.value

View on GitHub (pinned to 98b357f69e)

Solutions

  1. Register the option first: in a conftest.py pytest_addoption hook call parser.addini(name, help, type, default).
  2. Check the spelling/casing of the name against the addini registration and the getini call.
  3. If the option comes from a plugin, ensure the plugin is installed and loaded (pip show / pytest --trace-config).
  4. On version upgrades, consult the changelog for renamed/removed ini options.

Example fix

# before (conftest.py)
def pytest_configure(config):
    val = config.getini('my_flag')  # never registered

# after
def pytest_addoption(parser):
    parser.addini('my_flag', help='toggle', type='bool', default=False)
Defensive patterns

Strategy: validation

Validate before calling

def safe_getini(config, name, default=None):
    if name not in config._parser._inidict:
        return default
    return config.getini(name)

Type guard

def ini_is_registered(config, name: str) -> bool:
    return name in config._parser._inidict

Try / catch

try:
    val = config.getini(name)
except ValueError:
    val = None  # option not registered

Prevention

When it happens

Trigger: Calling config.getini('my_opt') in a conftest or plugin when no plugin has invoked parser.addini('my_opt', ...) in its pytest_addoption hook; using a misspelled or removed ini key; referencing an option from a plugin that is not installed.

Common situations: Typo in the ini key passed to getini; referencing a plugin-provided ini option without enabling the plugin; version upgrade where an ini option was renamed/removed (e.g. legacy options after a pytest major bump).

Related errors

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