pandas-dev/pandas · error · ValueError

Column length mismatch: {len(columns)} vs. {K}

Error message

Column length mismatch: {len(columns)} vs. {K}

What it means

Raised in SparseFrameAccessor._prep_index (used by from_spmatrix) when the number of column labels supplied does not equal K, the number of columns in the source sparse matrix. The labels cannot be mapped 1:1 to columns, so construction is rejected.

Source

Thrown at pandas/core/arrays/sparse/accessor.py:502

    @staticmethod
    def _prep_index(data, index, columns):
        from pandas.core.indexes.api import (
            default_index,
            ensure_index,
        )

        N, K = data.shape
        if index is None:
            index = default_index(N)
        else:
            index = ensure_index(index)
        if columns is None:
            columns = default_index(K)
        else:
            columns = ensure_index(columns)

        if len(columns) != K:
            raise ValueError(f"Column length mismatch: {len(columns)} vs. {K}")
        if len(index) != N:
            raise ValueError(f"Index length mismatch: {len(index)} vs. {N}")
        return index, columns

View on GitHub (pinned to 71959b8cb9)

Solutions

1. Size columns to the matrix: pass columns=None to let pandas default to RangeIndex, or build columns = [f'c{i}' for i in range(mat.shape[1])].
2. Assert len(columns) == mat.shape[1] before calling.
3. If columns come from another df, align after building: result.columns = source.columns.

Example fix

// before
pd.DataFrame.sparse.from_spmatrix(mat, columns=['a','b'])
// after
pd.DataFrame.sparse.from_spmatrix(mat, columns=[f'c{i}' for i in range(mat.shape[1])])

import pandas as pd

def from_spmatrix_safe(mat, columns=None, index=None):
    N, K = mat.shape
    if columns is not None and len(columns) != K:
        raise ValueError(f'columns len {len(columns)} != matrix cols {K}')
    return pd.DataFrame.sparse.from_spmatrix(mat, index=index, columns=columns)

def columns_match_matrix(columns, mat) -> bool:
    return columns is None or len(columns) == mat.shape[1]

try:
    return pd.DataFrame.sparse.from_spmatrix(mat, columns=columns)
except ValueError as e:
    if 'Column length mismatch' in str(e):
        columns = [f'c{i}' for i in range(mat.shape[1])]
        return pd.DataFrame.sparse.from_spmatrix(mat, columns=columns)
    raise

When it happens

Trigger: pd.DataFrame.sparse.from_spmatrix(scipy.sparse.eye(3), columns=['a','b']); passing a column list from a different-shaped matrix; reusing a stale columns list after the matrix changed shape.

Common situations: Hard-coded column lists that drift from the matrix width; slicing the sparse matrix but forgetting to slice the columns; off-by-one in column generation.

Related errors

• Index length mismatch: {len(index)} vs. {N}
• 'data' must have a single column, not '{ncol}'
• Function did not transform
• by_row={by_row} not allowed
• putmask: mask and data must be the same size

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