What causes "Option '{key}' is a reserved key" in pandas-dev/pandas?

Choose a different, non-reserved key name (ideally namespaced).

pandas-dev/pandas · error · OptionError

Option ' ' is a reserved key

Error message

Option '{key}' is a reserved key

What it means

Raised by `register_option` when the lowercased key is in `_reserved_keys`, which currently contains only `'all'`. Reserved keys have special meaning in the option API (e.g. `reset_option('all')`, `describe_option`) and cannot be registered.

Solutions

Choose a different, non-reserved key name (ideally namespaced).
Avoid bare generic names like `all`; check `_reserved_keys` (`['all']`) before registering.

Example fix

# before
register_option('all', True)   # OptionError: reserved key

# after
register_option('mylib.all_enabled', True)

Defensive patterns

Strategy: validation

Validate before calling

from pandas._config.config import _reserved_keys
def is_reserved(key: str) -> bool:
    return key.lower() in _reserved_keys
if not is_reserved(new_key):
    register_option(new_key, default)

Type guard

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

Try / catch

from pandas._config.config import OptionError
try:
    register_option(key, default)
except OptionError as e:
    if 'reserved key' in str(e):
        # rename key and retry
        ...
    raise

Prevention

Avoid generic key names like `all`; namespace everything you register.
Read `_reserved_keys` when generating keys programmatically.
Keep your key namespace distinct from pandas built-ins.

When it happens

Trigger: `register_option('all', ...)` (the only reserved key today).

Common situations: A library choosing a generic key name that happens to be reserved; future pandas versions adding more reserved keys that collide.

Related errors

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

Appendix: source

Thrown at pandas/_config/config.py:563

    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"

    for i, p in enumerate(path[:-1]):

View on GitHub (pinned to 3b7651241d)