pandas-dev/pandas · error · ValueError

Value must be a nonnegative integer or None

Error message

Value must be a nonnegative integer or None

What it means

Raised by the is_nonnegative_int validator (config.py:907-929), which accepts only None or an int >= 0. Any other type (str, float, negative int, bool-passed-as-int) raises ValueError. This validator is a public helper (cf.is_nonnegative_int) used by custom register_option calls and is exercised in tests (test_config.py:229).

Source

Thrown at pandas/_config/config.py:929

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

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

    elif isinstance(value, int):
        if value >= 0:
            return

    msg = "Value must be a nonnegative integer or None"
    raise ValueError(msg)


# common type validators, for convenience
# usage: register_option(... , validator = is_int)
is_int = is_type_factory(int)
is_bool = is_type_factory(bool)
is_float = is_type_factory(float)
is_str = is_type_factory(str)
is_text = is_instance_factory((str, bytes))


def is_callable(obj: object) -> bool:
    """

    Parameters
    ----------
    `obj` - the object to be checked

View on GitHub (pinned to 71959b8cb9)

Solutions

1. Convert the value to int first: pd.set_option('your.key', int(value)).
2. Use None instead of a negative number to mean 'unlimited'.
3. If reading from config, validate/coerce with int() in a try/except before calling set_option.

Example fix

# before
pd.set_option('display.max_rows', '-1')

# after
pd.set_option('display.max_rows', None)  # or a concrete int >= 0

value = get_raw()
if value is None or (isinstance(value, int) and not isinstance(value, bool) and value >= 0):
    pd.set_option('your.key', value)
else:
    raise ValueError('must be a nonnegative int or None')

def is_nonneg_int_or_none(value: object) -> bool:
    return value is None or (isinstance(value, int) and not isinstance(value, bool) and value >= 0)

When it happens

Trigger: Registering an option with validator=cf.is_nonnegative_int and then calling set_option with a negative int, a float like 1.5, a string '5', or any non-int non-None object. The default value passed at registration time is also validated, so a bad default (e.g. -2) triggers it immediately.

Common situations: Pulling a numeric setting from an env var or config file as a string and passing it straight to set_option; using a float where an integer count (rows, precision, display width) is required; attempting -1 as a sentinel.

Related errors

• Value must be an instance of {type_repr}
• Value must be one of {pp_values}
• 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/083e2ec8798a4c3a. Report an issue: GitHub.