What causes "Pattern matched multiple keys" in pandas-dev/pandas?

Use the full, exact option key (e.g. `display.max_columns`).

pandas-dev/pandas · error · OptionError

Pattern matched multiple keys

Error message

Pattern matched multiple keys

What it means

Raised by `_get_single_key` when `_select_options(pat)` returns more than one key, meaning the pattern is ambiguous. Because `pat` is matched with `re.search(..., re.I)` over all registered keys, short substrings like `display` or `max` hit many options and pandas refuses to guess.

Solutions

Use the full, exact option key (e.g. `display.max_columns`).
Add enough characters to make the pattern uniquely match a single key.
Call `pd.describe_option('yourpattern')` to see exactly which keys match before using get/set.

Example fix

# before
pd.get_option('max')   # matches max_rows, max_columns, ... -> OptionError

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

Defensive patterns

Strategy: validation

Validate before calling

from pandas._config.config import _select_options
def is_unique_option(pat: str) -> bool:
    matches = _select_options(pat)
    return len(matches) == 1, matches
unique, matches = is_unique_option('display')
if not unique:
    # lengthen pat or pick from matches

Type guard

def unique_option_match(pat: str) -> str | None:
    import pandas._config.config as c
    keys = c._select_options(pat)
    return keys[0] if len(keys) == 1 else None

Try / catch

from pandas._config.config import OptionError
try:
    pd.get_option(pat)
except OptionError as e:
    if 'Pattern matched multiple keys' in str(e):
        matches = pd._config.config._select_options(pat)
        # disambiguate by picking the intended full key
    ...

Prevention

Never rely on short substrings for production code; use full keys.
Use `pd.describe_option(pat)` to preview matches before get/set.
Add a regression note if a new option you register could make an existing partial match ambiguous.

When it happens

Trigger: `pd.get_option('display')`, `pd.get_option('max')`, or any substring/regex that matches two or more registered option keys.

Common situations: Using a partial option name for brevity; relying on a substring that later became ambiguous when pandas added a new option with a similar name (the documented stability warning in `get_option`).

Related errors

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

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