pandas-dev/pandas · error · ValueError

'values' must be a NumPy array, not

Error message

'values' must be a NumPy array, not {type(values).__name__}

What it means

Raised by NumpyExtensionArray.__init__ when values is neither a NumpyExtensionArray nor an np.ndarray. NumpyExtensionArray is a thin extension-array wrapper over a single numpy ndarray; the public constructor only accepts that raw ndarray. Lists, tuples, Series, Index objects, or scalars are rejected — callers should use pd.array() or np.asarray() first. Note this raises ValueError (not TypeError), which is slightly unusual.

Solutions

  1. Wrap in np.asarray first: pd.arrays.NumpyExtensionArray(np.asarray([1, 2, 3])).
  2. Prefer the factory: pd.array([1, 2, 3]) returns a NumpyExtensionArray for plain numpy dtypes.
  3. If starting from a Series, pass series.to_numpy().

Example fix

# before
pd.arrays.NumpyExtensionArray([1, 2, 3])  # raises

# after
pd.arrays.NumpyExtensionArray(np.asarray([1, 2, 3]))
Defensive patterns

Strategy: validation

Validate before calling

import numpy as np

def to_numpy_extension_array(values):
    if not isinstance(values, np.ndarray):
        values = np.asarray(values)
    return pd.arrays.NumpyExtensionArray(values)

Type guard

import numpy as np

def is_ndarray_or_nea(obj) -> bool:
    return isinstance(obj, (np.ndarray, pd.arrays.NumpyExtensionArray))

Try / catch

try:
    pd.arrays.NumpyExtensionArray(values)
except ValueError as e:
    if 'must be a NumPy array' in str(e):
        pd.arrays.NumpyExtensionArray(np.asarray(values))
    else:
        raise

Prevention

When it happens

Trigger: pd.arrays.NumpyExtensionArray([1, 2, 3]) — a Python list. pd.arrays.NumpyExtensionArray(pd.Series([1,2,3])). pd.arrays.NumpyExtensionArray('x'). Any path that hands a non-ndarray to the constructor directly.

Common situations: Users constructing NumpyExtensionArray explicitly (rather than via pd.array(..., dtype=numpy dtype)) and passing a list; tutorials that show the class but not the factory.

Related errors

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

Appendix: source

Thrown at pandas/core/arrays/numpy_.py:128

    # ExtensionBlock, search for `ABCNumpyExtensionArray`. We check for
    # that _typ to ensure that users don't unnecessarily use EAs inside
    # pandas internals, which turns off things like block consolidation.
    _typ = "npy_extension"
    __array_priority__ = 1000
    _ndarray: np.ndarray
    _dtype: NumpyEADtype
    _internal_fill_value = np.nan

    # ------------------------------------------------------------------------
    # Constructors

    def __init__(
        self, values: np.ndarray | NumpyExtensionArray, copy: bool = False
    ) -> None:
        if isinstance(values, type(self)):
            values = values._ndarray
        if not isinstance(values, np.ndarray):
            raise ValueError(
                f"'values' must be a NumPy array, not {type(values).__name__}"
            )

        if values.ndim == 0:
            # Technically we support 2, but do not advertise that fact.
            raise ValueError("NumpyExtensionArray must be 1-dimensional.")

        if copy:
            values = values.copy()

        dtype = NumpyEADtype(values.dtype)
        super().__init__(values, dtype)

    @classmethod
    def _from_sequence(
        cls, scalars, *, dtype: Dtype | None = None, copy: bool = False
    ) -> NumpyExtensionArray:
        if isinstance(dtype, NumpyEADtype):

View on GitHub (pinned to 3b7651241d)