pandas-dev/pandas · error · TypeError

mask should be boolean numpy array. Use the 'pd.array' funct

Error message

mask should be boolean numpy array. Use the 'pd.array' function instead

What it means

Raised by BaseMaskedArray.__init__ when the 'mask' argument is not a numpy ndarray of dtype bool. Masked arrays (Int8/Int16/.../Float64/Boolean) require the mask to be a real np.bool_ ndarray; passing a Python list, a pandas Series, or an int8 mask is rejected. The message points users to pd.array(...) which constructs masked arrays correctly from raw values.

Source

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

    """

    # our underlying data and mask are each ndarrays
    _data: np.ndarray
    _mask: npt.NDArray[np.bool_]

    @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)

View on GitHub (pinned to 71959b8cb9)

Solutions

Build the array via pd.array(values, dtype='Int64') rather than constructing the masked class directly.
If you must construct directly, convert the mask: mask = np.asarray(mask, dtype=bool).
Ensure mask is a numpy.ndarray before passing — isinstance(mask, np.ndarray) and mask.dtype == np.bool_.

Example fix

# before
from pandas.arrays import IntegerArray
IntegerArray(data, [True, False, True])

# after
pd.array([1, 2, pd.NA, 4], dtype='Int64')
# or
IntegerArray(data, np.array([True, False, True], dtype=bool))

Defensive patterns

Strategy: type-guard

Validate before calling

def as_bool_ndarray(mask):
    if isinstance(mask, np.ndarray) and mask.dtype == np.bool_:
        return mask
    return np.asarray(mask, dtype=bool)

Type guard

def is_bool_ndarray(mask) -> bool:
    return isinstance(mask, np.ndarray) and mask.dtype == np.bool_

Prevention

Construct masked arrays via pd.array(...) instead of direct class instantiation.
Always convert masks with np.asarray(mask, dtype=bool).
Avoid passing Python lists or pandas Series as masks.

When it happens

Trigger: Directly instantiating IntegerArray/BooleanArray/values with a Python list of booleans or a uint8 mask, instead of going through the public constructor.

Common situations: Third-party code subclassing or wrapping BaseMaskedArray; users hand-rolling masks from comparisons without converting to ndarray.

Related errors

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