pandas-dev/pandas · error · ValueError

Value must be one of

Error message

Value must be one of {pp_values}

What it means

Raised by `is_one_of_factory` when an option value is not in the enumerated legal values and also fails any predicate callables in the validator. pandas registers enum-style options (e.g. string scalers, plotting backends, styler renderers) with this factory. The message lists the legal values joined by `|`, and appends `or a callable` if the validator accepts callable predicates (used by options like `plotting.backend` or `display.html.table_schema`).

Solutions

1. Run `pd.describe_option('<name>')` and copy a value verbatim from the listed legal values.
2. For callable-accepting options, pass the function object, not its name as a string.
3. If the value legitimately should be allowed, register it through the documented public API rather than bypassing the validator.

Example fix

// before
pd.set_option('display.float_format', 'comma')

// after
pd.set_option('display.float_format', lambda v: f'{v:,.2f}')

import pandas as pd
doc = pd.describe_option(name)  # human-readable list of legal values
assert str(value) in doc or callable(value)

try:
    pd.set_option(name, value)
except ValueError:
    # revert to default and warn
    pd.reset_option(name)

When it happens

Trigger: `pd.set_option('plotting.backend', 'seaborn')` when seaborn isn't a registered backend; `pd.set_option('display.float_format', 'comma')` (string where a callable is required); `pd.set_option('mode.copy_on_write', 'yes')` instead of a legal value.

Common situations: Guessing an option value from memory instead of checking `describe_option`; passing a string when a callable is expected (float_format); version skew where a value was renamed/removed between pandas releases.

Related errors

• Must provide an even number of non-keyword arguments
• Value must be an instance of
• Value must have type
• is a python keyword
• is not a valid identifier

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

Appendix: source

Thrown at pandas/_config/config.py:902

        if not isinstance(x, _type):
            raise ValueError(f"Value must be an instance of {type_repr}")

    return inner


def is_one_of_factory(legal_values: Sequence) -> Callable[[Any], None]:
    callables = [c for c in legal_values if callable(c)]
    legal_values = [c for c in legal_values if not callable(c)]

    def inner(x: object) -> None:
        if x not in legal_values:
            if not any(c(x) for c in callables):
                uvals = [str(lval) for lval in legal_values]
                pp_values = "|".join(uvals)
                msg = f"Value must be one of {pp_values}"
                if len(callables):
                    msg += " or a callable"
                raise ValueError(msg)

    return inner


def is_nonnegative_int(value: object) -> None:
    """
    Verify that value is None or a positive int.

    Parameters
    ----------
    value : None or int
            The `value` to be checked.

    Raises
    ------
    ValueError
        When the value is not None or is a negative integer
    """

View on GitHub (pinned to 3b7651241d)