pandas-dev/pandas · error · ValueError

Value must be an instance of {type_repr}

Error message

Value must be an instance of {type_repr}

What it means

Raised by the is_instance_factory validator returned for pandas configuration options registered via register_option(). When you call pd.set_option() (or pd.option_context) with a value that is not an instance of the type the option requires, this ValueError fires. The concrete instance-based validator shipped in the library is is_text = is_instance_factory((str, bytes)), used for the 'display.encoding' option (config.py:938, display.py:61).

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 71959b8cb9)

Solutions

1. Pass a str or bytes value, e.g. pd.set_option('display.encoding', 'utf-8').
2. If you need the default back, use pd.reset_option('display.encoding') instead of setting None.
3. Check the registered validator with pd.describe_option('display.encoding') before setting.

Example fix

# before
pd.set_option('display.encoding', None)

# after
pd.reset_option('display.encoding')

import pandas as pd
value = get_value_from_config()
if not isinstance(value, (str, bytes)):
    raise TypeError(f'display.encoding must be str/bytes, got {type(value)}')
pd.set_option('display.encoding', value)

def is_valid_encoding(value: object) -> bool:
    return isinstance(value, (str, bytes))

When it happens

Trigger: Calling pd.set_option('display.encoding', <non-str-bytes>) — e.g. an int or None — runs the is_text validator and hits line 885. Any third-party code that registers its own option with validator=cf.is_instance_factory(SomeType) and then sets an incompatible value triggers the same path.

Common situations: Setting display.encoding to None to 'reset' it; passing an int or bool where a string codec name is expected; dynamic config where a variable of the wrong type flows into set_option.

Related errors

• Value must be one of {pp_values}
• Value must be a nonnegative integer or None
• Value must be a callable
• No such keys(s): {pat!r}
• Must provide an even number of non-keyword arguments

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