pandas-dev/pandas · error · ValueError

values.shape and mask.shape must match

Error message

values.shape and mask.shape must match

What it means

Raised by coerce_to_array at the end of normalization when the final values array and the final mask array have different shapes. The mask is derived either from the input, from isna(values), from the user-supplied mask, or from a combination; any path producing a mismatch trips this guard before construction.

Solutions

1. Verify mask.shape == values.shape before calling: assert mask.shape == values.shape.
2. Recompute the mask from the same values used: mask = isna(values).
3. Align lengths by re-indexing both arrays to a common index.

Example fix

// before
pd.array(np.array([True, False, True]), mask=np.array([False, True]), dtype='boolean')
// after
values = np.array([True, False, True])
mask = np.zeros(len(values), dtype=bool)
mask[1] = True
pd.array(values, mask=mask, dtype='boolean')

assert np.asarray(values).shape == np.asarray(mask).shape, 'values and mask shape mismatch'

def shapes_match(values, mask) -> bool:
    import numpy as np
    return np.asarray(values).shape == np.asarray(mask).shape

try:
    pd.array(values, mask=mask, dtype='boolean')
except ValueError as e:
    if 'shape' in str(e):
        mask = np.zeros(len(values), dtype=bool)
        ...

When it happens

Trigger: pd.array(values, mask=shorter_mask, dtype='boolean') where mask has a different length than values; passing a BooleanArray-derived values with an external mask whose length differs; supplying mask as a 2D array while values is 1D.

Common situations: Off-by-one in user-computed masks; masks computed against a filtered/extended version of the values; broadcasting mistakes where mask is scalar-shaped; reshaping values without reshaping mask.

Related errors

• cannot pass mask for BooleanArray input
• Need to pass bool-like values
• mask must be a 1D list-like
• Mismatched Period array lengths
• Array with ndim > 2 is not supported.

AI-assisted analysis of pandas-dev/pandas@3b7651241d (2026-08-11). Data as JSON: /api/errors/c762a3e7dc84f9f9. Report an issue: GitHub.

Appendix: source

Thrown at pandas/core/arrays/boolean.py:262

        ):
            raise TypeError("Need to pass bool-like values")

    if mask is None and mask_values is None:
        mask = np.zeros(values.shape, dtype=bool)
    elif mask is None:
        mask = mask_values
    elif isinstance(mask, np.ndarray) and mask.dtype == np.bool_:
        if mask_values is not None:
            mask = mask | mask_values
        elif copy:
            mask = mask.copy()
    else:
        mask = np.array(mask, dtype=bool)
        if mask_values is not None:
            mask = mask | mask_values

    if values.shape != mask.shape:
        raise ValueError("values.shape and mask.shape must match")

    return values, mask


@set_module("pandas.arrays")
class BooleanArray(BaseMaskedArray):
    """
    Array of boolean (True/False) data with missing values.

    This is a pandas Extension array for boolean data, under the hood
    represented by 2 numpy arrays: a boolean array with the data and
    a boolean array with the mask (True indicating missing).

    BooleanArray implements Kleene logic (sometimes called three-value
    logic) for logical operations. See :ref:`boolean.kleene` for more.

    To construct a BooleanArray from generic array-like input, use
    :func:`pandas.array` specifying ``dtype="boolean"`` (see examples

View on GitHub (pinned to 3b7651241d)