pandas-dev/pandas · error · OptionError

Option ' ' has already been defined as deprecated.

Error message

Option '{key}' has already been defined as deprecated.

What it means

Raised by `deprecate_option` when the (lowercased) key is already present in `_deprecated_options`. An option can only be deprecated once; calling `deprecate_option` twice for the same key — or deprecating a key pandas already deprecated internally — triggers this OptionError.

Solutions

1. Check `_deprecated_options` first: `from pandas._config.config import _deprecated_options; key in _deprecated_options`.
2. Deprecate each key exactly once; guard registration behind an idempotency check.
3. If pandas already deprecated the key, rely on its deprecation rather than adding your own.

Example fix

# before
from pandas._config.config import deprecate_option
deprecate_option('x', DeprecationWarning)
deprecate_option('x', DeprecationWarning)   # OptionError: already deprecated

# after
from pandas._config.config import deprecate_option, _deprecated_options
if 'x' not in _deprecated_options:
    deprecate_option('x', DeprecationWarning)

from pandas._config.config import _deprecated_options
def safe_deprecate(key: str, category):
    if key.lower() in _deprecated_options:
        return  # already deprecated
    from pandas._config.config import deprecate_option
    deprecate_option(key, category)

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

from pandas._config.config import OptionError
try:
    deprecate_option(key, category)
except OptionError:
    # already deprecated; nothing to do
    ...

When it happens

Trigger: `deprecate_option('x', DeprecationWarning)` called twice; or deprecating an option that pandas itself already marked deprecated in the current version.

Common situations: Library code deprecating an option that pandas deprecated in a newer release; re-running deprecation registration on module reload; double deprecation in tests.

Related errors

• No such keys(s) for
• No such keys(s)
• No such option
• Option ' ' has already been registered
• Pattern matched multiple keys

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

Appendix: source

Thrown at pandas/_config/config.py:650

    rkey : str, optional
        Name of an option to reroute access to.
        If specified, any referenced `key` will be
        re-routed to `rkey` including set/get/reset.
        rkey must be a fully-qualified option name (e.g "x.y.z.rkey").
        used by the default message if no `msg` is specified.
    removal_ver : str, optional
        Specifies the version in which this option will
        be removed. used by the default message if no `msg` is specified.

    Raises
    ------
    OptionError
        If the specified key has already been deprecated.
    """
    key = key.lower()

    if key in _deprecated_options:
        raise OptionError(f"Option '{key}' has already been defined as deprecated.")

    _deprecated_options[key] = DeprecatedOption(key, category, msg, rkey, removal_ver)


#
# functions internal to the module


def _select_options(pat: str) -> list[str]:
    """
    returns a list of keys matching `pat`

    if pat=="all", returns all registered options
    """
    # short-circuit for exact key
    if pat in _registered_options:
        return [pat]

View on GitHub (pinned to 3b7651241d)