pandas-dev/pandas · error · OptionError

Option '{key}' has already been registered

Error message

Option '{key}' has already been registered

What it means

Raised by register_option (config.py:560-561) when the lowercased key already exists in _registered_options. Option keys are case-insensitive and globally unique.

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

Solutions

  1. Guard with `if key not in cf._registered_options:` before registering.
  2. Use set_option on an already-registered key instead of register_option.
  3. Choose a namespaced unique key (e.g. under your library prefix).

Example fix

# before
import pandas._config.config as cf
cf.register_option('display.max_columns', 5)  # already registered

# after
import pandas._config.config as cf
if 'display.max_columns' not in cf._registered_options:
    cf.register_option('display.max_columns', 5)
Defensive patterns

Strategy: validation

Validate before calling

import pandas._config.config as cf
def safe_register(key, defval, **kw):
    key = key.lower()
    if key in cf._registered_options:
        return  # idempotent
    cf.register_option(key, defval, **kw)

Type guard

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

Try / catch

from pandas.errors import OptionError
try:
    cf.register_option(key, defval)
except OptionError:
    pass  # already registered; acceptable

Prevention

When it happens

Trigger: cf.register_option('display.max_columns', 5) when 'display.max_columns' is already registered (built-in).

Common situations: Re-running a notebook cell that registers a custom option; a library importing pandas-config twice; re-registering after a reload.

Related errors

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