{"record":{"id":"190a11920fe0c126","repo":"pandas-dev/pandas","slug":"column-length-mismatch-len-columns-vs-k","errorCode":null,"errorMessage":"Column length mismatch: {len(columns)} vs. {K}","messagePattern":"Column length mismatch: (.+?) vs\\. (.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"pandas/core/arrays/sparse/accessor.py","lineNumber":502,"sourceCode":"    @staticmethod\n    def _prep_index(data, index, columns):\n        from pandas.core.indexes.api import (\n            default_index,\n            ensure_index,\n        )\n\n        N, K = data.shape\n        if index is None:\n            index = default_index(N)\n        else:\n            index = ensure_index(index)\n        if columns is None:\n            columns = default_index(K)\n        else:\n            columns = ensure_index(columns)\n\n        if len(columns) != K:\n            raise ValueError(f\"Column length mismatch: {len(columns)} vs. {K}\")\n        if len(index) != N:\n            raise ValueError(f\"Index length mismatch: {len(index)} vs. {N}\")\n        return index, columns\n","sourceCodeStart":484,"sourceCodeEnd":506,"githubUrl":"https://github.com/pandas-dev/pandas/blob/3b7651241d4da534b3559b60ef128e1c34f54116/pandas/core/arrays/sparse/accessor.py#L484-L506","documentation":"Raised by SparseFrameAccessor._prep_index (used by from_spmatrix) when len(columns) does not equal K, the second dimension of the source sparse matrix. The provided column labels must exactly cover the matrix's column count.","triggerScenarios":"pd.DataFrame.sparse.from_spmatrix(mat, columns=['a','b']) where mat.shape == (N, 3); passing a Index/Series of column names with the wrong length.","commonSituations":"Hard-coded column list that drifted from matrix shape; reusing columns from a different matrix; transposing the matrix but not the labels.","solutions":["Pass columns=None to let pandas assign a RangeIndex.","Build columns from shape: columns=[f'c{i}' for i in range(mat.shape[1])].","Validate len(columns) == mat.shape[1] before calling."],"exampleFix":"# before\npd.DataFrame.sparse.from_spmatrix(mat, columns=['a','b'])  # mat is (5,3)\n# after\ncols = [f'c{i}' for i in range(mat.shape[1])]\npd.DataFrame.sparse.from_spmatrix(mat, columns=cols)","handlingStrategy":"validation","validationCode":"def columns_match_matrix(columns, mat) -> bool:\n    return columns is None or len(columns) == mat.shape[1]","typeGuard":"def valid_columns_for(columns, mat) -> bool:\n    return columns is None or len(list(columns)) == mat.shape[1]","tryCatchPattern":"try:\n    df = pd.DataFrame.sparse.from_spmatrix(mat, columns=columns)\nexcept ValueError as e:\n    if 'Column length mismatch' in str(e):\n        df = pd.DataFrame.sparse.from_spmatrix(mat)  # default RangeIndex\n    else:\n        raise","preventionTips":["Derive columns from mat.shape[1]: [f'c{i}' for i in range(mat.shape[1])].","Pass columns=None when labels are not strictly required.","Add a unit test that pins column count vs matrix shape."],"tags":["pandas","sparse","shape","scipy"],"backgroundTag":null,"analyzedSha":"3b7651241d4da534b3559b60ef128e1c34f54116","analyzedAt":"2026-08-11T22:10:44.015Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}