What causes "values.shape must match mask.shape" in pandas-dev/pandas?

Slice or pad the mask to match: mask = mask[:len(values)] or rebuild via pd.array(...).

pandas-dev/pandas · error · ValueError

values.shape must match mask.shape

Error message

values.shape must match mask.shape

What it means

Raised by BaseMaskedArray.__init__ when len(values) != len(mask). The data buffer and the mask must align element-for-element; a length mismatch indicates a programming error in how the masked array is being assembled.

Source

Thrown at pandas/core/arrays/masked.py:159

    @classmethod
    def _simple_new(cls, values: np.ndarray, mask: npt.NDArray[np.bool_]) -> Self:
        result = BaseMaskedArray.__new__(cls)
        result._data = values
        result._mask = mask
        return result

    def __init__(
        self, values: np.ndarray, mask: npt.NDArray[np.bool_], copy: bool = False
    ) -> None:
        # values is supposed to already be validated in the subclass
        if not (isinstance(mask, np.ndarray) and mask.dtype == np.bool_):
            raise TypeError(
                "mask should be boolean numpy array. Use "
                "the 'pd.array' function instead"
            )
        if values.shape != mask.shape:
            raise ValueError("values.shape must match mask.shape")

        if copy:
            values = values.copy()
            mask = mask.copy()

        self._data = values
        self._mask = mask

    @classmethod
    def _from_sequence(cls, scalars, *, dtype=None, copy: bool = False) -> Self:
        values, mask = cls._coerce_to_array(scalars, dtype=dtype, copy=copy)
        return cls(values, mask)

    def _cast_pointwise_result(self, values) -> ArrayLike:
        if isna(values).all():
            return type(self)._from_sequence(values, dtype=self.dtype)
        if not (isinstance(values, np.ndarray) and values.dtype == object):
            values = construct_1d_object_array_from_listlike(values)

View on GitHub (pinned to 71959b8cb9)

Solutions

Slice or pad the mask to match: mask = mask[:len(values)] or rebuild via pd.array(...).
Always derive the mask from the same source as values, e.g. mask = isna(values).
Prefer pd.array(values, dtype=...) which handles mask construction internally.

Example fix

# before
IntegerArray(np.arange(5), np.zeros(3, dtype=bool))

# after
mask = np.zeros(len(data), dtype=bool)
IntegerArray(data, mask)

Defensive patterns

Strategy: validation

Validate before calling

def matched_mask(values, mask):
    mask = np.asarray(mask, dtype=bool)
    if mask.shape != values.shape:
        raise ValueError(f'mask shape {mask.shape} != values shape {values.shape}')
    return mask

Type guard

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

Prevention

Derive masks from the same source as values: mask = isna(values).
Assert shapes match before constructing masked arrays.
Prefer pd.array(...) for public construction.

When it happens

Trigger: Constructing a masked array subclass directly with values of length N and mask of length M != N (e.g. data = np.arange(5), mask = np.zeros(3, bool)).

Common situations: Off-by-one slicing of the mask, reuse of a mask from a different column, or building arrays element-wise without recomputing the mask.

Related errors

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