pandas-dev/pandas · error · ValueError

axis(={axis}) out of bounds

Error message

axis(={axis}) out of bounds

What it means

Raised by SparseArray.cumsum when `axis` is not None and axis >= self.ndim (which is 1 for a 1-D SparseArray). It mimics ndarray.cumsum's bounds check so that passing axis=1 on a 1-D sparse array surfaces a clear error rather than silently being ignored or mis-shaping the result.

Source

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

        When performing the cumulative summation, any non-NA/null values will
        be skipped. The resulting SparseArray will preserve the locations of
        NaN values, but the fill value will be `np.nan` regardless.

        Parameters
        ----------
        axis : int or None
            Axis over which to perform the cumulative summation. If None,
            perform cumulative summation over flattened array.

        Returns
        -------
        cumsum : SparseArray
        """
        nv.validate_cumsum(args, kwargs)

        if axis is not None and axis >= self.ndim:  # Mimic ndarray behaviour.
            raise ValueError(f"axis(={axis}) out of bounds")

        if not self._null_fill_value:
            return SparseArray(self.to_dense(), fill_value=np.nan).cumsum()

        return SparseArray(
            self.sp_values.cumsum(),
            sparse_index=self.sp_index,
            fill_value=self.fill_value,
        )

    def mean(self, axis: Axis = 0, *args, skipna: bool = True, **kwargs):
        """
        Mean of non-NA/null values.

        Parameters
        ----------
        axis : int, default 0
            Not Used. NumPy compatibility.

View on GitHub (pinned to 71959b8cb9)

Solutions

1. Pass axis=0 (or None) for a 1-D SparseArray: sparse_arr.cumsum(axis=0).
2. Drop the axis argument entirely since 1-D cumsum ignores it when valid.
3. If you genuinely need 2-D, operate on a DataFrame with sparse dtype and ensure the column count justifies axis=1.

Example fix

// before
out = sparse_arr.cumsum(axis=1)  # raises 'axis(=1) out of bounds'

// after
out = sparse_arr.cumsum(axis=0)

def cumsum_safe(arr, axis=0):
    if axis is not None and axis >= arr.ndim:
        raise ValueError(f'axis(={axis}) out of bounds for ndim={arr.ndim}')
    return arr.cumsum(axis=axis)

def axis_is_valid(arr, axis) -> bool:
    return axis is None or -arr.ndim <= axis < arr.ndim

try:
    out = arr.cumsum(axis=axis)
except ValueError as e:
    if 'out of bounds' in str(e):
        out = arr.cumsum(axis=0)
    else:
        raise

When it happens

Trigger: sparse_arr.cumsum(axis=1), df.cummax(axis=1) on a sparse-backed DataFrame column broadcast with an axis arg, or code that assumes 2-D semantics.

Common situations: Generic axis-handling code written for DataFrames applied to a Series/SparseArray, or copy-paste from a 2-D reduction into a 1-D cumsum call.

Related errors

• index is out of bounds: must be an integer between -{n} and
• `axis` must be fewer than the number of dimensions ({ndim})
• cannot diff {type(arr).__name__} on axis={axis}
• Named aggregation is not supported when {axis=}.
• Operation {func} does not support axis=1

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