pandas-dev/pandas · error · ValueError

Value must be an instance of

Error message

Value must be an instance of {type_repr}

What it means

Raised by `is_instance_factory` when a value passed to a registered pandas option fails an `isinstance` check against the configured type(s). pandas uses these validators to enforce option value types at `set_option` time. The message names the expected type (or a pipe-joined list when the validator accepts a tuple). It is a hard ValueError meant to stop invalid configuration from silently corrupting downstream behavior.

Solutions

1. Read the message's expected type and coerce the value to that exact python type before calling set_option.
2. If loading from text config, write a small mapper that casts known options (int options -> int(), bool options -> str.lower() in {'true','1'}) before applying.
3. Confirm the option's registered validator with `pd.describe_option(name)` to see the allowed type before assigning.

Example fix

// before
pd.set_option('display.max_rows', '100')

// after
pd.set_option('display.max_rows', 100)

def safe_set_option(name, value):
    import pandas as pd
    pd.describe_option(name)  # raises if unknown
    # describe_option prints the registered type in its docstring
    pd.set_option(name, value)

def is_int_like(v) -> bool:
    return isinstance(v, int) and not isinstance(v, bool)

try:
    pd.set_option(name, value)
except ValueError as e:
    # log and fall back to a known-good default
    pd.set_option(name, default)

When it happens

Trigger: Calling `pd.set_option('display.max_rows', 'ten')` (string instead of int), `pd.set_option('mode.sim_interactive', 1)` (int instead of bool), or any `set_option`/option_context whose value fails the validator registered via `is_instance_factory` (used widely for display, indexing, and copy-on-write options).

Common situations: Loading config from YAML/ENV as strings and forwarding it straight into set_option; using numpy types where python builtins are expected (e.g. np.int64 vs int); interactive notebooks where a user reassigns an option with a wrong type.

Related errors

• Must provide an even number of non-keyword arguments
• Value must be one of
• Value must have type
• Can only string multiply by an integer.
• DateOffset is intra-day and cannot be applied to…

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

Appendix: source

Thrown at pandas/_config/config.py:885

    Parameters
    ----------
    `_type` - the type to be checked against

    Returns
    -------
    validator - a function of a single argument x , which raises
                ValueError if x is not an instance of `_type`

    """
    if isinstance(_type, tuple):
        type_repr = "|".join(map(str, _type))
    else:
        type_repr = f"'{_type}'"

    def inner(x: object) -> None:
        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)

View on GitHub (pinned to 3b7651241d)