pandas-dev/pandas · error · OptionError

Option ' ' is a prefix of an already-registered option

Error message

Option '{key}' is a prefix of an already-registered option

What it means

Raised by `register_option` (GH#29242) when the target slot already holds a dict — i.e. a namespace with already-registered child options already lives at `key`. Registering a scalar here would clobber those children, so it is rejected. This is the inverse of errors 15/16: here the new key would shadow existing children rather than nest under an existing leaf.

Solutions

1. Do not register a key that is a prefix of existing options; choose a non-overlapping key.
2. If you intend to remove the children, deprecate them first, then register the leaf.
3. Namespace your own keys (e.g. `mylib.*`) so they cannot collide with built-in namespaces like `display`.

Example fix

# before
register_option('a.b', 1)
register_option('a', 2)   # OptionError: 'a' is a prefix of an already-registered option

# after
register_option('a_root', 2)   # does not shadow the 'a.*' namespace

from pandas._config.config import _global_config
def key_is_not_prefix_of_existing(key: str) -> bool:
    parts = key.split('.')
    cursor = _global_config
    for p in parts[:-1]:
        cursor = cursor.get(p, {})
    return not isinstance(cursor.get(parts[-1]), dict)

def key_shadows_namespace(key: str) -> bool:
    import pandas._config.config as c
    parts = key.split('.')
    cursor = c._global_config
    for p in parts[:-1]:
        cursor = cursor.get(p, {})
    return isinstance(cursor.get(parts[-1]), dict)

from pandas._config.config import OptionError
try:
    register_option(key, default)
except OptionError as e:
    if 'prefix of an already-registered option' in str(e):
        # key would clobber children; choose a different key and retry
        ...
    raise

When it happens

Trigger: First `register_option('a.b', 1)` and `register_option('a.c', 2)` (so `a` is a namespace dict), then `register_option('a', 3)` — registering `a` as a leaf would destroy `a.b` and `a.c`.

Common situations: Trying to promote a namespace to a leaf after children were registered; auto-generated keys that collapse a parent namespace.

Related errors

• Path prefix to option
• is a python keyword
• is not a valid identifier
• Option ' ' has already been registered
• Option ' ' is a reserved key

AI-assisted analysis of pandas-dev/pandas@3b7651241d (2026-08-11). Data as JSON: /api/errors/2d826ad441d59efa. Report an issue: GitHub.

Appendix: source

Thrown at pandas/_config/config.py:595

    cursor = _global_config
    msg = "Path prefix to option '{option}' is already an option"

    for i, p in enumerate(path[:-1]):
        if not isinstance(cursor, dict):
            raise OptionError(msg.format(option=".".join(path[:i])))
        if p not in cursor:
            cursor[p] = {}
        cursor = cursor[p]

    if not isinstance(cursor, dict):
        raise OptionError(msg.format(option=".".join(path[:-1])))

    # a namespace already lives here, i.e. `key` is a path prefix to one or
    # more already-registered options; registering it would clobber them
    # (GH#29242)
    if isinstance(cursor.get(path[-1]), dict):
        raise OptionError(f"Option '{key}' is a prefix of an already-registered option")

    cursor[path[-1]] = defval  # initialize

    # save the option metadata
    _registered_options[key] = RegisteredOption(
        key=key, defval=defval, doc=doc, validator=validator, cb=cb
    )


def deprecate_option(
    key: str,
    category: type[Warning],
    msg: str | None = None,
    rkey: str | None = None,
    removal_ver: str | None = None,
) -> None:
    """
    Mark option `key` as deprecated, if code attempts to access this option,

View on GitHub (pinned to 3b7651241d)