pandas-dev/pandas · error · OptionError

Path prefix to option '{option}' is already an option

Error message

Path prefix to option '{option}' is already an option

What it means

Raised by register_option (config.py:581-583) when, while walking the dotted key path, a non-final segment resolves to a value that is already a leaf (not a dict). The option being registered would have to traverse an existing leaf to reach a subtree, which is illegal.

Source

Thrown at pandas/_config/config.py:583

    # the default value should be legal
    if validator:
        validator(defval)

    # walk the nested dict, creating dicts as needed along the path
    path = key.split(".")

    for k in path:
        if not re.match("^" + tokenize.Name + "$", k):
            raise ValueError(f"{k} is not a valid identifier")
        if keyword.iskeyword(k):
            raise ValueError(f"{k} is a python keyword")

    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

View on GitHub (pinned to 71959b8cb9)

Solutions

  1. Register the prefix as a namespace first (only leaf-level options are stored as values; intermediate nodes become dicts automatically only when they are prefixes of newly registered leaves).
  2. Rename the new option to avoid colliding with an existing leaf path.
  3. Inspect _global_config to see which prefix is already a leaf.

Example fix

# before
cf.register_option('display.x', 1)
cf.register_option('display.x.y', 2)  # Path prefix to option 'display.x' is already an option

# after
cf.register_option('display.x_val', 1)
cf.register_option('display.x.y', 2)
Defensive patterns

Strategy: validation

Validate before calling

import pandas._config.config as cf
def safe_register(key, defval, **kw):
    cursor = cf._global_config
    for i, seg in enumerate(key.lower().split('.')[:-1]):
        if seg not in cursor:
            break
        cursor = cursor[seg]
        if not isinstance(cursor, dict):
            raise ValueError(f'prefix {".".join(key.split(".")[:i+1])} is already a leaf')
    cf.register_option(key, defval, **kw)

Try / catch

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

Prevention

When it happens

Trigger: cf.register_option('a.b.c', 1) when 'a.b' is already registered as a leaf value (e.g. an int). The walk hits cursor that is not a dict at index i.

Common situations: Registering a deeper option under a prefix previously registered as a plain value; mis-ordered registration calls.

Related errors

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