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 `is_nonnegative_int`, the validator used for options that accept `None` or a nonnegative python int (e.g. `display.max_rows`, `display.max_columns`, `display.width` when None means unlimited). It explicitly rejects negative ints, booleans (which are technically ints but semantically wrong), floats, and strings. `None` short-circuits as 'unlimited'.

Solutions

1. Use None to mean 'unlimited' rather than -1.
2. Coerce the value with `int(x)` after confirming `x >= 0`.
3. Avoid passing numpy scalars; convert with `int(np_value)` first.

Example fix

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

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

def coerce_nonneg_int(v):
    if v is None:
        return None
    iv = int(v)
    if iv < 0:
        raise ValueError('must be >=0 or None')
    return iv

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

When it happens

Trigger: `pd.set_option('display.max_rows', -1)`; `pd.set_option('display.max_columns', 5.0)` (float); `pd.set_option('display.max_rows', '50')` (string); passing a numpy integer where a plain int is required may also fail the `isinstance(value, int)` branch for some configurations.

Common situations: Off-by-one thinking where -1 means 'all' (it does not — None does); JSON config decoded into floats; using np.int64 from array operations as the value.

Related errors

• Value must be a callable
• is a python keyword
• is not a valid identifier
• Must provide an even number of non-keyword arguments
• No such keys(s) for

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

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