pandas-dev/pandas · error · TypeError

values should be {descr} numpy array. Use the 'pd.array' fun

Error message

values should be {descr} numpy array. Use the 'pd.array' function instead

What it means

Raised by NumericArray.__init__ when the values passed directly to the constructor are not a numpy ndarray of the correct numeric kind (integer for IntegerArray, floating for FloatingArray). The masked-array constructor is a low-level API expecting pre-validated _data/_mask buffers; user code should use pd.array(...) instead, which performs inference, casting, and mask construction.

Source

Thrown at pandas/core/arrays/numeric.py:269

class NumericArray(BaseMaskedArray):
    """
    Base class for IntegerArray and FloatingArray.
    """

    _dtype_cls: type[NumericDtype]

    def __init__(
        self, values: np.ndarray, mask: npt.NDArray[np.bool_], copy: bool = False
    ) -> None:
        checker = self._dtype_cls._checker
        if not (isinstance(values, np.ndarray) and checker(values.dtype)):
            descr = (
                "floating"
                if self._dtype_cls.kind == "f"  # type: ignore[comparison-overlap]
                else "integer"
            )
            raise TypeError(
                f"values should be {descr} numpy array. Use "
                "the 'pd.array' function instead"
            )
        if values.dtype == np.float16:
            # If we don't raise here, then accessing self.dtype would raise
            raise TypeError("FloatingArray does not support np.float16 dtype.")

        # NB: if is_nan_na() is True
        #  then caller is responsible for ensuring
        #  assert mask[np.isnan(values)].all()

        super().__init__(values, mask, copy=copy)

    @cache_readonly
    def dtype(self) -> NumericDtype:
        mapping = self._dtype_cls._get_dtype_mapping()
        return mapping[self._data.dtype]

View on GitHub (pinned to 71959b8cb9)

Solutions

1. Use the public factory: pd.array(values, dtype='Int64').
2. If you must call the constructor, convert values first: IntegerArray(np.asarray(values, dtype=np.int64), mask).
3. Ensure values.dtype matches the array class's numpy_dtype.

Example fix

// before
IntegerArray([1, 2, 3], mask=[False, False, True])  # raises: values should be integer numpy array

// after
pd.array([1, 2, None], dtype="Int64")

import numpy as np

def validate_numeric_array_inputs(values, mask, kind):
    arr = np.asarray(values)
    if arr.dtype.kind != kind:
        raise TypeError(f"values must be {kind} numpy array, got {arr.dtype}")
    if np.asarray(mask).ndim != 1:
        raise TypeError("mask must be 1D")
    return arr, np.asarray(mask, dtype=bool)

def is_correct_kind_numpy(values, kind) -> bool:
    import numpy as np
    return isinstance(values, np.ndarray) and values.dtype.kind == kind

try:
    arr = IntegerArray(values, mask)
except TypeError as e:
    if "Use the 'pd.array' function instead" in str(e):
        arr = pd.array(values, dtype="Int64")
    else:
        raise

When it happens

Trigger: Calling IntegerArray(values, mask) or FloatingArray(values, mask) directly with values that are a Python list, an object array, or a numpy array of the wrong kind (e.g. IntegerArray(np.array([1.0,2.0]), mask)).

Common situations: Users reaching for the internal constructor instead of the public pd.array factory; passing already-float data to IntegerArray expecting automatic conversion.

Related errors

• values should be boolean numpy array. Use the 'pd.array' fun
• closed keyword does not match dtype.closed
• must not have differing left [{type(left).__name__}] and rig
• category, object, and string subtypes are not supported for
• Period dtypes are not supported, use a PeriodIndex instead

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