pandas-dev/pandas · error · TypeError

values should be numpy array. Use the 'pd.array' function…

Error message

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

What it means

Raised by NumericArray.__init__ when the values argument is not a NumPy array whose dtype passes the dtype class's _checker (is_integer_dtype for IntegerArray, is_floating_dtype for FloatingArray). The constructor is the low-level path: it expects raw, correctly-typed data plus a mask. The error message explicitly redirects users to pd.array(), which runs full coercion (_coerce_to_data_and_mask) including dtype inference and casting.

Solutions

Use the public factory: pd.array(values, dtype='Int64') or pd.array(values, dtype='Float64').
If you must call the constructor, pre-coerce values to the right numpy kind: np.asarray(values, dtype=np.int64) for IntegerArray, np.float64 for FloatingArray.
Construct via the Series astype path: pd.Series(values).astype('Int64').array.

Example fix

# before
pd.arrays.IntegerArray(np.array([1.5, 2.0]), mask=np.zeros(2, bool))  # raises

# after
pd.array([1.5, 2.0], dtype='Int64')

Defensive patterns

Strategy: fallback

Validate before calling

import numpy as np

def build_masked_array(values, mask, *, kind):
    np_kind = {'int': 'int64', 'float': 'float64'}[kind]
    values = np.asarray(values, dtype=np_kind)
    # ensure the dtype class's _checker will pass
    return values, np.asarray(mask, dtype=bool)

Type guard

def matches_numeric_kind(values, kind) -> bool:
    import numpy as np
    v = np.asarray(values)
    return (kind == 'i' and v.dtype.kind in 'iu') or (kind == 'f' and v.dtype.kind == 'f')

Try / catch

# Prefer: don't catch — just use the factory.
pd.array(values, dtype='Int64')  # runs full coercion

Prevention

Use pd.array(values, dtype=...) instead of calling IntegerArray/FloatingArray constructors directly.
If you must call the constructor, pre-coerce with np.asarray(values, dtype=np.int64/np.float64).
Treat the constructor as internal; the factory is the public contract.

When it happens

Trigger: pd.arrays.IntegerArray(np.array([1.5, 2.0]), mask=np.zeros(2, bool)) — float values into integer array. pd.arrays.FloatingArray(np.array([1, 2], dtype='int64'), mask=...) — integer values into floating array. Constructing directly from a Python list.

Common situations: Users discovering pd.arrays.IntegerArray / FloatingArray and calling the constructor directly instead of the documented pd.array() factory; internal code that forgot to coerce before reaching __init__.

Related errors

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

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