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

Pick a namespaced key like 'mylib.all' instead of bare 'all'.

pandas-dev/pandas · error · OptionError

Option '{key}' is a reserved key

Error message

Option '{key}' is a reserved key

What it means

Raised by register_option (config.py:562-563) when the key is in _reserved_keys, which currently contains only 'all'. Reserved keys have special meaning in the config API and cannot be reused.

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

Solutions

Pick a namespaced key like 'mylib.all' instead of bare 'all'.
Check cf._reserved_keys before registering to surface the conflict early.
Avoid top-level reserved words when designing an option namespace.

Example fix

# before
import pandas._config.config as cf
cf.register_option('all', True)  # reserved key

# after
cf.register_option('myapp.all', True)

Defensive patterns

Strategy: validation

Validate before calling

import pandas._config.config as cf
def safe_register(key, defval, **kw):
    if key.lower() in cf._reserved_keys:
        raise ValueError(f'{key!r} is reserved; pick a different name')
    cf.register_option(key, defval, **kw)

Type guard

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

Prevention

Namespace every custom option under a library prefix (e.g. 'myapp.').
Avoid bare generic words like 'all' as option names.
Check cf._reserved_keys at design time.

When it happens

Trigger: cf.register_option('all', True) — 'all' is reserved because reset_option('all') resets every option.

Common situations: Picking a short, generic option name that collides with the reserved vocabulary.

Related errors

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