pandas-dev/pandas · error · OptionError

Option '{key}' 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 (config.py:594-595) when the final segment of the new key already maps to a dict in the cursor — i.e. the new key is a prefix of an already-registered option and would clobber a subtree (GH#29242). The check uses isinstance(cursor.get(path[-1]), dict).

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 71959b8cb9)

Solutions

1. Register under a different top-level name that is not already a subtree.
2. Use the existing leaf option under that namespace via set_option.
3. Inspect the existing subtree (pd.describe_option('prefix')) before registering.

Example fix

# before
cf.register_option('display', 1)  # prefix of already-registered option

# after
cf.register_option('myapp.display', 1)

import pandas._config.config as cf
def is_not_prefix(key: str) -> bool:
    cursor = cf._global_config
    for seg in key.lower().split('.')[:-1]:
        cursor = cursor.get(seg, {})
    return not isinstance(cursor.get(key.split('.')[-1]), dict)

from pandas.errors import OptionError
try:
    cf.register_option(key, defval)
except OptionError:
    cf.register_option(renamed_key, defval)

When it happens

Trigger: cf.register_option('display', 1) when 'display.max_columns' etc. already exist; registering a parent that shadows existing children.

Common situations: Trying to 'simplify' the namespace by registering a short key that is already a namespace.

Related errors

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

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