pandas-dev/pandas · error · OptionError

Option ' ' has already been registered

Error message

Option '{key}' has already been registered

What it means

Raised by `register_option` when the lowercased `key` is already present in `_registered_options`. Keys are case-insensitive (lowercased before lookup), so re-registering under a different case still collides. pandas itself registers the built-in options during import, so common keys like `display.max_rows` are already taken.

Solutions

  1. Pick a unique, namespaced key (e.g. prefix with your package name: `mylib.feature.flag`).
  2. Check existence first: `from pandas._config.config import _registered_options; key in _registered_options`.
  3. Call `pd._config.config._registered_options[key].defval` and reuse rather than re-register if you just want the default.

Example fix

# before
from pandas._config.config import register_option
register_option('display.max_rows', 10)   # OptionError: already registered

# after
from pandas._config.config import register_option, _registered_options
key = 'mylib.something.enabled'
if key not in _registered_options:
    register_option(key, True)
Defensive patterns

Strategy: validation

Validate before calling

from pandas._config.config import register_option, _registered_options
def safe_register(key: str, default, **kw):
    key = key.lower()
    if key in _registered_options:
        return  # already registered; reuse
    register_option(key, default, **kw)

Type guard

def is_registered(key: str) -> bool:
    import pandas._config.config as c
    return key.lower() in c._registered_options

Try / catch

from pandas._config.config import OptionError
try:
    register_option(key, default)
except OptionError:
    # key already owned; reuse or pick a namespaced key
    ...

Prevention

When it happens

Trigger: `register_option('display.max_rows', 10)` (pandas already registered it), or calling `register_option` twice with the same key.

Common situations: A third-party library trying to register a key pandas already owns; duplicate registration across modules; re-running a registration on notebook reload.

Related errors

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

Appendix: source

Thrown at pandas/_config/config.py:561

        Function of a single argument, should raise `ValueError` if
        called with a value which is not a legal value for the option.
    cb
        a function of a single argument "key", which is called
        immediately after an option value is set/reset. key is
        the full name of the option.

    Raises
    ------
    ValueError if `validator` is specified and `defval` is not a valid value.

    """
    import keyword
    import tokenize

    key = key.lower()

    if key in _registered_options:
        raise OptionError(f"Option '{key}' has already been registered")
    if key in _reserved_keys:
        raise OptionError(f"Option '{key}' is a reserved key")

    # 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"

View on GitHub (pinned to 3b7651241d)