pandas-dev/pandas · error · ValueError

NumpyExtensionArray must be 1-dimensional.

Error message

NumpyExtensionArray must be 1-dimensional.

What it means

Raised by NumpyExtensionArray.__init__ when values.ndim == 0 (a 0-dimensional/scalar ndarray). The comment in source notes that 2-D arrays are technically supported internally but not advertised, while 0-D scalars are explicitly rejected because ExtensionArrays are defined to be 1-dimensional sequences.

Source

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

    _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):
            dtype = dtype._dtype
        if dtype is not None:
            dtype = np.dtype(dtype)  # type: ignore[arg-type]

        if dtype is not None and dtype.kind in "iu":
            # GH#41724 - validate NaN before casting float -> int

View on GitHub (pinned to 71959b8cb9)

Solutions

1. Wrap the scalar in a 1-element 1-D array: np.array([value], dtype=...).
2. If you meant to store a single value, construct pd.array([value]).
3. Check values.ndim before construction and reshape/ravel as needed.

Example fix

# before
pd.arrays.NumpyExtensionArray(np.array(5))
# after
pd.arrays.NumpyExtensionArray(np.array([5]))

import numpy as np

def ensure_1d_ndarray(values) -> np.ndarray:
    arr = np.asarray(values)
    if arr.ndim == 0:
        arr = arr.reshape(1)
    return arr

import numpy as np

def is_1d_ndarray(values) -> bool:
    return isinstance(values, np.ndarray) and values.ndim >= 1

try:
    arr = pd.arrays.NumpyExtensionArray(values)
except ValueError:
    arr = pd.arrays.NumpyExtensionArray(np.atleast_1d(values))

When it happens

Trigger: Passing np.array(5) (a scalar wrapped as 0-d ndarray), np.asarray(some_scalar), or any operation that produces a 0-dimensional ndarray into NumpyExtensionArray().

Common situations: Calling np.asarray on a Python scalar then wrapping it. Reducing an array with keepdims in a way that yields ndim 0. Misunderstanding that NumpyExtensionArray models a Sequence, not a scalar box.

Related errors

• 'values' must be a NumPy array, not {type(values).__name__}
• Invalid dtype {dtype} for PeriodArray
• Incorrect dtype
• dtype is not specified and cannot be inferred
• PeriodArray does not allow floating point in construction

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