pandas-dev/pandas · error · OptionError

You can only set the value of existing options

Error message

You can only set the value of existing options

What it means

Raised by DictWrapper.__setattr__ (config.py:418-428) when assigning an attribute that is not an existing leaf option. The attribute-style API (pd.options.display.x = v) only supports overwriting existing values, never creating new keys or subtrees.

Source

Thrown at pandas/_config/config.py:428

    """provide attribute-style access to a nested dict"""

    d: dict[str, Any]

    def __init__(self, d: dict[str, Any], prefix: str = "") -> None:
        object.__setattr__(self, "d", d)
        object.__setattr__(self, "prefix", prefix)

    def __setattr__(self, key: str, val: Any) -> None:
        prefix = object.__getattribute__(self, "prefix")
        if prefix:
            prefix += "."
        prefix += key
        # you can't set new keys
        # can you can't overwrite subtrees
        if key in self.d and not isinstance(self.d[key], dict):
            set_option(prefix, val)
        else:
            raise OptionError("You can only set the value of existing options")

    def __getattr__(self, key: str) -> Any:
        prefix = object.__getattribute__(self, "prefix")
        if prefix:
            prefix += "."
        prefix += key
        try:
            v = object.__getattribute__(self, "d")[key]
        except KeyError as err:
            raise OptionError("No such option") from err
        if isinstance(v, dict):
            return DictWrapper(v, prefix)
        else:
            return get_option(prefix)

    def __dir__(self) -> list[str]:
        return list(self.d.keys())

View on GitHub (pinned to 71959b8cb9)

Solutions

1. Register the option first with cf.register_option('display.new_thing', 5).
2. Set existing options via set_option('display.new_thing', 5) once registered.
3. Use the attribute API only for keys already present in pd.describe_option().

Example fix

# before
pd.options.display.my_width = 100  # You can only set the value of existing options

# after
import pandas._config.config as cf
cf.register_option('display.my_width', 100, validator=cf.is_int)
pd.options.display.my_width = 200

def set_attr_option(root, key, value):
    # root is e.g. pd.options.display; verify key is an existing leaf
    if key not in dir(root) or isinstance(getattr(root, key, None), type(root)):
        raise AttributeError(f'{key} is not an existing option on {root}')
    setattr(root, key, value)

def is_settable_leaf(root, key: str) -> bool:
    d = object.__getattribute__(root, 'd')
    return key in d and not isinstance(d[key], dict)

from pandas.errors import OptionError
try:
    setattr(pd.options.display, key, value)
except OptionError:
    print(f'{key} is not registered; call register_option first')

When it happens

Trigger: pd.options.display.new_thing = 5, or assigning into a namespace prefix (pd.options.display = {...}) where 'display' maps to a sub-dict, not a leaf.

Common situations: Assuming pd.options behaves like a plain dict and trying to add a custom setting via attribute assignment.

Related errors

• No such option
• No such keys(s): {pat!r}
• Pattern matched multiple keys
• Must provide an even number of non-keyword arguments
• No such keys(s) for {pat=}

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