What causes "expected dimension <= 1 data" in pandas-dev/pandas?

Flatten explicitly if appropriate: pd.arrays.SparseArray(arr.ravel()).

pandas-dev/pandas · error · TypeError

expected dimension <= 1 data

Error message

expected dimension <= 1 data

What it means

Raised by the module-level _make_sparse helper (used by the SparseArray constructor and astype) when the input ndarray has arr.ndim > 1. SparseArray only models 1-D sparsity, so a 2-D array would need an unsupported sp_index shape; the constructor refuses up front.

Source

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

    """
    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 71959b8cb9)

Solutions

Flatten explicitly if appropriate: pd.arrays.SparseArray(arr.ravel()).
Build sparse arrays per column: [pd.arrays.SparseArray(c) for c in arr.T].
For 2-D sparse storage use scipy.sparse directly (and pd.DataFrame.sparse.from_spmatrix).

Example fix

// before
sa = pd.arrays.SparseArray(np.zeros((3, 4)))  # raises 'expected dimension <= 1'

// after
sa = pd.arrays.SparseArray(np.zeros((3, 4)).ravel())

Defensive patterns

Strategy: type-guard

Validate before calling

import numpy as np
import pandas as pd

def to_sparse_1d(values, fill_value=None):
    arr = np.asarray(values)
    if arr.ndim > 1:
        raise TypeError(f'expected 1-D, got ndim={arr.ndim}')
    return pd.arrays.SparseArray(arr, fill_value=fill_value)

Type guard

import numpy as np

def is_1d(values) -> bool:
    return np.asarray(values).ndim <= 1

Try / catch

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

Prevention

Select single columns with df['x'] not df[['x']] before sparse conversion
Use scipy.sparse for 2-D sparse storage instead of SparseArray
Validate ndim == 1 at the boundary to your sparse pipeline

When it happens

Trigger: pd.arrays.SparseArray(np.zeros((3,4))), pd.Series(np.eye(3)).astype('Sparse[int64]') (rare; mostly direct ndarray), or piping a 2-D matrix through a code path expecting a vector.

Common situations: Treating a DataFrame column slice as 1-D when it is actually 2-D (e.g. df[['x']] vs df['x']), or applying sparse conversion to a feature matrix expecting per-column sparse arrays.

Related errors

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