Pandas: ValueError: Shape of passed values is (X, Y), indices imply (A, B)

Verified FixPython 3.10+Pandas 2.2+, NumPy 1.26+Silo: pandas

Quick Fix / Solution Rapide

This error occurs when Python tries to construct a DataFrame where the dimensions of the underlying data matrix do not match the number of index rows or column headers provided. Align matrix dimensions or use DataFrame.from_records().

Root Cause Analysis

This error occurs when Python attempts to instantiate a Pandas DataFrame where the shape of the raw input array or nested list contradicts the lengths of the specified index or columns arguments.

Root Cause 1: Row Count Mismatch on Axis 0

When passing a NumPy 2D array of shape (N, M) to pd.DataFrame(data, index=custom_index), Pandas expects len(custom_index) to equal N exactly. If custom_index contains fewer or more elements than N, Pandas raises ValueError: Shape of passed values is (M, N), indices imply (len(columns), len(index)).

Root Cause 2: Column Count Mismatch on Axis 1

Similarly, if you pass a list of column names whose length does not equal M (the number of columns in the 2D array), Pandas cannot map headers to the data columns unambiguously, triggering a dimensional shape mismatch error.

Root Cause 3: Confusing Rows and Columns in Nested Lists

When converting nested Python lists (e.g. [[1, 2, 3], [4, 5, 6]]), developers frequently confuse whether inner lists represent rows or columns. By default, Pandas interprets outer elements as rows and inner elements as columns. Constructing a DataFrame with column labels meant for transposed data causes immediate dimension collision.

Root Cause 4: Assigning Incompatible Arrays to Existing DataFrames

Attempting to assign a 1D or 2D array to a subset of DataFrame columns where the length of the array does not match the length of the DataFrame index triggers shape mismatch errors during column broadcasting.

Reproduction Code (MCVE)

Example: Bug Reproduction

import pandas as pd
import numpy as np

# A 2x2 matrix (2 rows, 2 columns)
matrix = np.array([[10, 20], [30, 40]])

# Providing 4 index row labels for a 2-row matrix triggers ValueError
row_labels = ["row_1", "row_2", "row_3", "row_4"]
col_labels = ["col_A", "col_B"]

df = pd.DataFrame(matrix, index=row_labels, columns=col_labels)

Solution 1: Verify and Reshape Data Dimensions Before Instantiation

Inspect data.shape and ensure the lengths of index and columns match the 2D dimensions exactly, or transpose the matrix with .T if orientations are swapped.

Example: Recommended Solution

import pandas as pd
import numpy as np

matrix = np.array([[10, 20], [30, 40]])

# Match row labels to matrix.shape[0] and col labels to matrix.shape[1]
num_rows, num_cols = matrix.shape
row_labels = [f"row_{i}" for i in range(num_rows)]
col_labels = [f"col_{j}" for j in range(num_cols)]

df = pd.DataFrame(matrix, index=row_labels, columns=col_labels)
print("Correctly dimensioned DataFrame:")
print(df)

Solution 2: Use Dictionary Construction or Transposition

Construct DataFrames using dictionaries of columns or list of records, which allows Pandas to infer row indices automatically without manual dimension tracking.

Example: Alternative Solution

import pandas as pd

# Method A: Construct from dictionary of named series/lists
data_dict = {
    "product_id": [101, 102, 103],
    "price": [29.99, 49.50, 15.00],
    "in_stock": [True, True, False]
}
df_dict = pd.DataFrame(data_dict)
print("DataFrame from dictionary:")
print(df_dict)

# Method B: Construct from list of records
records = [
    {"user": "Alice", "score": 95},
    {"user": "Bob", "score": 88},
    {"user": "Charlie", "score": 92}
]
df_records = pd.DataFrame.from_records(records)
print("\nDataFrame from records:")
print(df_records)

A classic edge case occurs when creating a DataFrame from a 1D array while specifying column names: pd.DataFrame(np.array([1, 2, 3]), columns=['A', 'B', 'C']). A 1D array of shape (3,) is treated as 3 rows with 1 column, NOT 1 row with 3 columns. To create a 1-row DataFrame from a 1D array, reshape it first using arr.reshape(1, -1).

Another frequent mistake is appending a single Series to an existing DataFrame where index alignment causes the Series to be interpreted as a column rather than a new row.

Contrast this error with ValueError: Length of values does not match length of index: Length mismatch occurs when assigning an array of wrong length to a specific existing column (df['new_col'] = [1, 2]), whereas the shape mismatch error occurs during initial DataFrame matrix construction.

Previous Next