pandas-dev/pandas · error · ValueError

Index length mismatch: {len(index)} vs. {N}

Error message

Index length mismatch: {len(index)} vs. {N}

What it means

Raised in SparseFrameAccessor._prep_index when the supplied row index length does not equal N, the number of rows of the source sparse matrix. The index must label every row, so a mismatch is rejected.

Source

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

        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. Pass index=None to default to RangeIndex, or build index = existing_index[:mat.shape[0]].
2. Assert len(index) == mat.shape[0] before calling.
3. Re-derive the index from the matrix shape: index = pd.RangeIndex(mat.shape[0]).

Example fix

// before
pd.DataFrame.sparse.from_spmatrix(mat, index=df.index)
// after
pd.DataFrame.sparse.from_spmatrix(mat, index=df.index[:mat.shape[0]])

import pandas as pd

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

def index_match_matrix(index, mat) -> bool:
    return index is None or len(index) == mat.shape[0]

try:
    return pd.DataFrame.sparse.from_spmatrix(mat, index=index)
except ValueError as e:
    if 'Index length mismatch' in str(e):
        return pd.DataFrame.sparse.from_spmatrix(mat)  # default RangeIndex
    raise

When it happens

Trigger: pd.DataFrame.sparse.from_spmatrix(scipy.sparse.eye(3), index=[1,2]); passing a DatetimeIndex from a different-length source; reusing an index after filtering the matrix rows.

Common situations: Index inherited from a pre-filter df that had more/fewer rows than the matrix; timezone/time mismatches producing wrong-length indexes; concat/slice drift.

Related errors

• Column length mismatch: {len(columns)} vs. {K}
• '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/6a012d9d94268476. Report an issue: GitHub.