pandas-dev/pandas · error · ValueError

'data' must have a single column, not '{ncol}'

Error message

'data' must have a single column, not '{ncol}'

What it means

Raised in SparseArray.from_spmatrix when the input scipy sparse matrix has more than one column. SparseArray is 1-D, so only a single-column matrix can be flattened into it; multi-column matrices must go through DataFrame.sparse.from_spmatrix instead.

Source

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

            sparse matrix with a single column.

        Returns
        -------
        SparseArray

        Examples
        --------
        >>> import scipy.sparse
        >>> mat = scipy.sparse.coo_matrix((4, 1))
        >>> pd.arrays.SparseArray.from_spmatrix(mat)
        <SparseArray>
        [0.0, 0.0, 0.0, 0.0]
        Length: 4, dtype: Sparse[float64, 0.0]
        """
        length, ncol = data.shape

        if ncol != 1:
            raise ValueError(f"'data' must have a single column, not '{ncol}'")

        # our sparse index classes require that the positions be strictly
        # increasing. So we need to sort loc, and arr accordingly.
        data_csc = data.tocsc()
        data_csc.sort_indices()
        arr = data_csc.data
        idx = data_csc.indices

        zero = np.array(0, dtype=arr.dtype).item()
        dtype = SparseDtype(arr.dtype, zero)
        index = IntIndex(length, idx)

        return cls._simple_new(arr, index, dtype)

    def __array__(
        self, dtype: NpDtype | None = None, copy: bool | None = None
    ) -> np.ndarray:
        if self.sp_index.ngaps == 0:

View on GitHub (pinned to 71959b8cb9)

Solutions

1. Use DataFrame.sparse.from_spmatrix for multi-column matrices.
2. Reshape/slice the matrix to one column first: mat = scipy.sparse.csc_matrix(vec).reshape(-1,1).
3. If you genuinely have one column, ensure shape is (n,1): assert mat.shape[1] == 1.

Example fix

// before
pd.arrays.SparseArray.from_spmatrix(scipy.sparse.eye(3))
// after
pd.DataFrame.sparse.from_spmatrix(scipy.sparse.eye(3))

import pandas as pd

def from_spmatrix_1d(mat):
    if mat.shape[1] != 1:
        raise ValueError(f'matrix has {mat.shape[1]} columns; use DataFrame.sparse.from_spmatrix')
    return pd.arrays.SparseArray.from_spmatrix(mat)

def is_single_column_matrix(mat) -> bool:
    return hasattr(mat, 'shape') and len(mat.shape) == 2 and mat.shape[1] == 1

try:
    return pd.arrays.SparseArray.from_spmatrix(mat)
except ValueError as e:
    if 'single column' in str(e):
        return pd.DataFrame.sparse.from_spmatrix(mat)
    raise

When it happens

Trigger: pd.arrays.SparseArray.from_spmatrix(scipy.sparse.eye(3)); passing a CSR/CSC matrix with shape (n, k>1); from_spmatrix(mat) where mat was built from a 2-D array.

Common situations: Treating a 2-D sparse matrix as 1-D; reusing a matrix constructor that defaults to square shape; forgetting that scipy.sparse differentiates 1-D vs 2-D.

Related errors

• Column length mismatch: {len(columns)} vs. {K}
• Index length mismatch: {len(index)} vs. {N}
• Cannot construct {type(self).__name__} from scalar data. Pas
• Unable to avoid copy while creating an array as requested.
• Cannot modify read-only array

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