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__` (the `pd.options.<...> = value` API) when assigning to an attribute that is not an existing leaf option. The wrapper only allows overwriting a registered leaf value; setting a brand-new attribute or writing into a subtree namespace is rejected. New options must be registered via `register_option`, not assigned.

Solutions

1. Assign only to an existing leaf, e.g. `pd.options.display.max_rows = 10`.
2. To create a new option use `pd.set_option(key, value)` after `pd.core.config_init` or call `pd._config.config.register_option(key, default)`.
3. Fix typos against `dir(pd.options)` / `pd.describe_option()`.

Example fix

# before
pd.options.display.mycustom = 5   # OptionError

# after
pd.options.display.max_rows = 10  # existing leaf
# or register a new one:
from pandas._config.config import register_option
register_option('display.mycustom', 5)

import pandas as pd
def set_via_options(path: str, value):
    parts = path.split('.')
    node = pd.options
    for p in parts[:-1]:
        node = getattr(node, p)
    if not isinstance(getattr(node, parts[-1], None), dict) and parts[-1] in dir(node):
        setattr(node, parts[-1], value)
    else:
        raise ValueError(f'{path} is not an existing leaf option')

def is_settable_leaf(path: str) -> bool:
    import pandas as pd
    parts = path.split('.')
    node = pd.options
    for p in parts[:-1]:
        node = getattr(node, p, None)
        if node is None:
            return False
    return parts[-1] in dir(node) and not isinstance(getattr(node, parts[-1]), dict)

from pandas._config.config import OptionError
try:
    setattr(pd.options.display, attr, value)
except OptionError:
    # use set_option() or register a new option instead
    ...

When it happens

Trigger: `pd.options.foo = 1`, `pd.options.display.new_setting = 5`, or any assignment to a path that is not a registered scalar option.

Common situations: Trying to create a custom option by attribute assignment (not supported); typo on an existing leaf; writing to an intermediate namespace node instead of a leaf.

Related errors

• No such keys(s)
• No such option
• Must provide an even number of non-keyword arguments
• No such keys(s) for
• Option ' ' has already been defined as deprecated.

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

Appendix: 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 3b7651241d)