pandas-dev/pandas · error · TypeError

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

Error message

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

What it means

Raised in BaseMaskedArray.__init__ when 'mask' is not a numpy ndarray of dtype bool. The constructor is internal API; users should construct masked arrays (IntegerArray, BooleanArray, FloatingArray, etc.) via pd.array(...) which coerces inputs correctly.

Solutions

Use pd.array(values, dtype='Int64') (or the appropriate masked dtype) for public construction.
If extending BaseMaskedArray, convert the mask with np.asarray(mask, dtype=bool) before calling super().__init__.

Example fix

// before
pd.arrays.IntegerArray(values, [True, False, True])
// after
pd.array(values, dtype='Int64')

Defensive patterns

Strategy: type-guard

Validate before calling

import numpy as np

def coerce_mask(mask):
    m = np.asarray(mask)
    if m.dtype != np.bool_:
        m = m.astype(bool)
    return m

Type guard

import numpy as np

def is_bool_ndarray(m):
    return isinstance(m, np.ndarray) and m.dtype == np.bool_

Prevention

Use pd.array(values, dtype=...) for public construction of masked arrays.
Subclass authors: convert the mask to np.bool_ in __init__ before super().
Never pass Python lists or integer 0/1 arrays as the mask directly.

When it happens

Trigger: pd.arrays.IntegerArray(values, [True, False]) (list mask); SomeMaskedArray(values, np.array([1, 0])) (non-bool dtype); direct subclass construction with a Python list mask.

Common situations: Direct construction by users or extension authors bypassing pd.array; passing Python lists/tuples as masks; passing integer 0/1 masks.

Related errors

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

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