pytest-dev/pytest · error · ValueError

alias {alias!r} conflicts with existing configuration option

Error message

alias {alias!r} conflicts with existing configuration option

What it means

Raised by Parser.addini() when an alias passed via the aliases= parameter collides with an already-registered ini option name. Aliases must not shadow canonical option names. This is a registration-time ValueError surfaced during plugin/conftest loading.

Source

Thrown at src/_pytest/config/argparsing.py:360

            ini_type = tuple(
                _ini_type_to_member(name, member) for member in get_args(type)
            )
        else:
            ini_type = _ini_type_to_member(name, type)
        if default is NOTSET:
            if isinstance(ini_type, (tuple, _IniLiteral)):
                kind = "union" if isinstance(ini_type, tuple) else "Literal"
                raise ValueError(
                    f"ini option {name!r} has a {kind} type, which has no "
                    "implicit default; pass an explicit `default` to `addini`"
                )
            default = get_ini_default_for_type(ini_type)

        self._inidict[name] = (help, ini_type, default)

        for alias in aliases:
            if alias in self._inidict:
                raise ValueError(
                    f"alias {alias!r} conflicts with existing configuration option"
                )
            if (already := self._ini_aliases.get(alias)) is not None:
                raise ValueError(f"{alias!r} is already an alias of {already!r}")
            self._ini_aliases[alias] = name


def get_ini_default_for_type(type: _IniTypeTag) -> Any:
    """
    Used by addini to get the default value for a given config option type, when
    default is not supplied.
    """
    if type in ("paths", "pathlist", "args", "linelist"):
        return []
    elif type == "bool":
        return False
    elif type == "int":
        return 0

View on GitHub (pinned to 98b357f69e)

Solutions

1. Rename the alias to something not already registered as an ini option.
2. Reorder addini calls so the alias does not collide, or remove the conflicting registration.
3. Check existing ini options via `pytest --help` or config._parser._inidict when debugging plugin load order.

Example fix

# before
parser.addini('bar', help='...')
parser.addini('foo', aliases=['bar'], help='...')  # collides

# after
parser.addini('foo', aliases=['foo_alt'], help='...')

def check_alias_not_an_option(parser_inidict: dict, alias: str) -> None:
    if alias in parser_inidict:
        raise ValueError(f'alias {alias!r} conflicts with existing configuration option')

When it happens

Trigger: Calling parser.addini('foo', ..., aliases=['bar']) when 'bar' was already added as a canonical ini option by an earlier addini call. The check at line 359 finds alias in self._inidict.

Common situations: Two plugins where one's alias matches another's option name; renaming an option and adding the old name as an alias while another plugin already registered that name; typos causing accidental collisions.

Related errors

• {alias!r} is already an alias of {already!r}
• invalid type for ini option {name!r}: {type_!r} (expected on
• invalid type for ini option {name!r}: Literal choices must b
• ini option {name!r} has a {kind} type, which has no implicit
• option names {conflict} already added

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