pandas-dev/pandas · error · OptionError

Pattern matched multiple keys

Error message

Pattern matched multiple keys

What it means

Raised by _get_single_key (config.py:133-134) when the supplied pattern matches more than one registered option key. The API requires an unambiguous match because get/set operate on a single value; multiple matches are rejected rather than guessing.

Source

Thrown at pandas/_config/config.py:134

    >>> pd.options.context
    Traceback (most recent call last):
    OptionError: No such option
    """

    __module__ = "pandas.errors"


#
# User API


def _get_single_key(pat: str) -> str:
    keys = _select_options(pat)
    if len(keys) == 0:
        _warn_if_deprecated(pat)
        raise OptionError(f"No such keys(s): {pat!r}")
    if len(keys) > 1:
        raise OptionError("Pattern matched multiple keys")
    key = keys[0]

    _warn_if_deprecated(key)

    key = _translate_key(key)

    return key


def get_option(pat: str) -> Any:
    """
    Retrieve the value of the specified option.

    This method allows users to query the current value of a given option
    in the pandas configuration system. Options control various display,
    performance, and behavior-related settings within pandas.

    Parameters

View on GitHub (pinned to 71959b8cb9)

Solutions

1. Use the fully-qualified option name, e.g. 'display.max_columns' instead of 'display'.
2. Use pd.describe_option(pat) to see which keys the pattern resolves to, then narrow the pattern.
3. Pin the full key in a constant rather than relying on partial matching.

Example fix

# before
pd.get_option('display')  # Pattern matched multiple keys

# after
pd.get_option('display.max_columns')

import pandas._config.config as cf
def is_unambiguous(pat: str) -> bool:
    return len(cf._select_options(pat)) == 1
assert is_unambiguous(pat), f'{pat!r} is ambiguous or unknown'

def is_single_match(pat: str) -> bool:
    import pandas._config.config as cf
    return len(cf._select_options(pat)) == 1

from pandas.errors import OptionError
try:
    pd.get_option(pat)
except OptionError as e:
    if 'multiple keys' in str(e):
        matches = cf._select_options(pat)
        pat = matches[0] if len(matches) == 1 else None

When it happens

Trigger: pd.get_option('display') matches display.max_rows, display.max_columns, etc. Likewise pd.set_option('display', 5) or pd.reset_option('display.max') (here reset raises the 4-char rule instead).

Common situations: Using an over-broad prefix to be 'convenient', then a future pandas release adds another option sharing that prefix, making a previously-unique match ambiguous.

Related errors

• No such keys(s): {pat!r}
• Value must be a positive integer or None
• Value must be one of python|pyarrow
• 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/9093eb8c4f37d6a4. Report an issue: GitHub.