What causes "limit must be None" in pandas-dev/pandas?

Drop the limit argument: sparse_arr.fillna(0).

pandas-dev/pandas · error · ValueError

limit must be None

Error message

limit must be None

What it means

Raised by SparseArray.fillna when `limit` is not None. SparseArray.fillna replaces every NA in sp_values with the scalar fill in one vectorized np.where; it cannot cap the number of consecutive fills, so the limit parameter is unsupported and must be left at None.

Source

Thrown at pandas/core/arrays/sparse/array.py:863

        Notes
        -----
        When `value` is specified, the result's ``fill_value`` depends on
        ``self.fill_value``. The goal is to maintain low-memory use.

        If ``self.fill_value`` is NA, the result dtype will be
        ``SparseDtype(self.dtype, fill_value=value)``. This will preserve
        amount of memory used before and after filling.

        When ``self.fill_value`` is not NA, the result dtype will be
        ``self.dtype``. Again, this preserves the amount of memory used.
        """
        if isinstance(value, dict):
            raise TypeError(
                "ExtensionArray.fillna does not support filling with a dict. "
                "Use Series.fillna instead."
            )
        if limit is not None:
            raise ValueError("limit must be None")
        new_values = np.where(isna(self.sp_values), value, self.sp_values)

        if self._null_fill_value:
            # This is essentially just updating the dtype.
            new_dtype = SparseDtype(self.dtype.subtype, fill_value=value)
        else:
            new_dtype = self.dtype

        return self._simple_new(new_values, self._sparse_index, new_dtype)

    def shift(self, periods: int = 1, fill_value=None) -> Self:
        if not len(self) or periods == 0:
            return self.copy()

        if isna(fill_value):
            fill_value = self.dtype.na_value

        subtype = np.result_type(fill_value, self.dtype.subtype)

View on GitHub (pinned to 71959b8cb9)

Solutions

Drop the limit argument: sparse_arr.fillna(0).
If you need a fill limit, use Series-level ffill/bfill: pd.Series(arr).ffill(limit=1).
Pre-limit the NAs yourself then fill the remainder with a scalar.

Example fix

// before
arr.fillna(0, limit=1)
// after
pd.Series(arr).ffill(limit=1).fillna(0).array

Defensive patterns

Strategy: validation

Validate before calling

import pandas as pd

def fillna_sparse_no_limit(arr, value, limit=None):
    if limit is not None:
        return pd.Series(arr).ffill(limit=limit).fillna(value).array
    return arr.fillna(value)

Type guard

def limit_is_none(limit) -> bool:
    return limit is None

Try / catch

try:
    return arr.fillna(value, limit=limit)
except ValueError as e:
    if 'limit must be None' in str(e):
        return pd.Series(arr).ffill(limit=limit).fillna(value).array
    raise

Prevention

Don't forward limit to SparseArray.fillna.
Use Series.ffill/bfill when a fill cap is required.
Strip limit from generic fillna wrappers for sparse arrays.

When it happens

Trigger: sparse_arr.fillna(0, limit=1); forwarding a limit kwarg from Series.fillna (which has limit support) down to the EA fillna.

Common situations: Generic fillna wrappers that always pass limit; migrating dense forward-fill code with limit to sparse; UI/config exposing a 'max fills' option.

Related errors

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