pandas-dev/pandas · error · TypeError

expected dimension <= 1 data

Error message

expected dimension <= 1 data

What it means

Thrown by the internal _make_sparse helper (pandas/core/arrays/sparse/array.py:2146) which converts a numpy ndarray into pandas' sparse representation. SparseArray is fundamentally 1-D, so the helper hard-rejects any array whose ndim exceeds 1 before computing the sparsity mask. The TypeError (not ValueError) signals the input shape is structurally wrong for the sparse code path, not merely an invalid value.

Solutions

1. Flatten the input to 1-D before construction: pd.arrays.SparseArray(arr.ravel()) or pass a Series (pd.Series(arr.ravel(), dtype='Sparse[int]').
2. Select a single column from a DataFrame before sparse conversion: df['col'].astype('Sparse[int]') instead of df.astype(...).
3. Validate shape upstream with assert arr.ndim == 1 before calling sparse APIs.

Example fix

// before
import numpy as np, pandas as pd
arr = np.zeros((3, 4))
pd.arrays.SparseArray(arr)  # raises TypeError

// after
pd.arrays.SparseArray(arr.ravel())

import numpy as np
def to_sparse_safe(arr):
    arr = np.asarray(arr)
    if arr.ndim > 1:
        arr = arr.ravel()
    return pd.arrays.SparseArray(arr)

def is_1d(nd: np.ndarray) -> bool:
    return getattr(nd, 'ndim', None) == 1

try:
    sa = pd.arrays.SparseArray(arr)
except TypeError as e:
    if 'expected dimension' in str(e):
        sa = pd.arrays.SparseArray(np.asarray(arr).ravel())
    else:
        raise

When it happens

Trigger: Constructing a SparseArray from a 2-D numpy array or DataFrame values: pd.arrays.SparseArray(np.zeros((3,4))). Calling any SparseArray operation that routes the backing ndarray through _make_sparse with >1-D data. Indirectly triggered by pd.Series(...).astype('Sparse[int]') when the Series was built from a DataFrame column slice that retained 2-D shape.

Common situations: User flattens a DataFrame incorrectly (df.values instead of df[col].values) and feeds it to a sparse dtype. Aggregation pipelines that preserve 2-D shape through to a sparse cast. Reading a single-column DataFrame and passing df rather than df.iloc[:,0].

Related errors

• Unable to avoid copy while creating an array as requested.
• axis(= ) out of bounds
• Can only use the '.sparse' accessor with Sparse data.
• Cannot apply ufunc to mixed DataFrame and Series inputs.
• Cannot construct from scalar data. Pass a sequence instead.

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

Appendix: source

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

    """
    Convert ndarray to sparse format

    Parameters
    ----------
    arr : ndarray
    kind : {'block', 'integer'}
    fill_value : NaN or another value
    dtype : np.dtype, optional
    copy : bool, default False

    Returns
    -------
    (sparse_values, index, fill_value) : (ndarray, SparseIndex, Scalar)
    """
    assert isinstance(arr, np.ndarray)

    if arr.ndim > 1:
        raise TypeError("expected dimension <= 1 data")

    if fill_value is None:
        fill_value = na_value_for_dtype(arr.dtype)

    if isna(fill_value):
        mask = notna(arr)
    else:
        # cast to object comparison to be safe
        if is_string_dtype(arr.dtype):
            arr = arr.astype(object)

        if is_object_dtype(arr.dtype):
            # element-wise equality check method in numpy doesn't treat
            # each element type, eg. 0, 0.0, and False are treated as
            # same. So we have to check the both of its type and value.
            mask = splib.make_mask_object_ndarray(arr, fill_value)
        else:
            mask = arr != fill_value

View on GitHub (pinned to 3b7651241d)