pandas-dev/pandas · error · ValueError

values.shape must match mask.shape

Error message

values.shape must match mask.shape

What it means

Raised in BaseMaskedArray.__init__ when values.shape != mask.shape. The data array and the boolean mask must be element-aligned; mismatched shapes are rejected to prevent silent misalignment of NA markers.

Solutions

1. Ensure the mask is generated from the same axis/length as the values.
2. Broadcast or truncate intentionally before constructing, and assert equality.
3. Prefer pd.array(...) which derives the mask consistently from the input.

Example fix

// before
IntegerArray(values[:5], mask[:4])
// after
assert values.shape == mask.shape
IntegerArray(values, mask)

import numpy as np

def build_masked_inputs(values, mask):
    values = np.asarray(values)
    mask = np.asarray(mask, dtype=bool)
    assert values.shape == mask.shape, (values.shape, mask.shape)
    return values, mask

def shapes_match(values, mask):
    return values.shape == mask.shape

When it happens

Trigger: IntegerArray(values, mask) where len(values) != len(mask); constructing with mask derived from a differently-sized array.

Common situations: Mismatched lengths from independent computations; off-by-one in mask construction; broadcasting mistakes.

Related errors

• cannot assign mismatch length to masked array
• mask should be boolean numpy array. Use the 'pd.array'…
• values should be numpy array. Use the 'pd.array' function…
• > 1 ndim Categorical are not supported at this time
• can only perform ops with 1-d structures

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

Appendix: 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 3b7651241d)