{"record":{"id":"8e949984b3d9d01e","repo":"pandas-dev/pandas","slug":"numpyextensionarray-must-be-1-dimensional","errorCode":null,"errorMessage":"NumpyExtensionArray must be 1-dimensional.","messagePattern":"NumpyExtensionArray must be 1-dimensional\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"pandas/core/arrays/numpy_.py","lineNumber":134,"sourceCode":"    _dtype: NumpyEADtype\n    _internal_fill_value = np.nan\n\n    # ------------------------------------------------------------------------\n    # Constructors\n\n    def __init__(\n        self, values: np.ndarray | NumpyExtensionArray, copy: bool = False\n    ) -> None:\n        if isinstance(values, type(self)):\n            values = values._ndarray\n        if not isinstance(values, np.ndarray):\n            raise ValueError(\n                f\"'values' must be a NumPy array, not {type(values).__name__}\"\n            )\n\n        if values.ndim == 0:\n            # Technically we support 2, but do not advertise that fact.\n            raise ValueError(\"NumpyExtensionArray must be 1-dimensional.\")\n\n        if copy:\n            values = values.copy()\n\n        dtype = NumpyEADtype(values.dtype)\n        super().__init__(values, dtype)\n\n    @classmethod\n    def _from_sequence(\n        cls, scalars, *, dtype: Dtype | None = None, copy: bool = False\n    ) -> NumpyExtensionArray:\n        if isinstance(dtype, NumpyEADtype):\n            dtype = dtype._dtype\n        if dtype is not None:\n            dtype = np.dtype(dtype)  # type: ignore[arg-type]\n\n        if dtype is not None and dtype.kind in \"iu\":\n            # GH#41724 - validate NaN before casting float -> int","sourceCodeStart":116,"sourceCodeEnd":152,"githubUrl":"https://github.com/pandas-dev/pandas/blob/71959b8cb9b2459c16e14b34f28b178ccfe14735/pandas/core/arrays/numpy_.py#L116-L152","documentation":"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.","triggerScenarios":"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().","commonSituations":"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.","solutions":["Wrap the scalar in a 1-element 1-D array: np.array([value], dtype=...).","If you meant to store a single value, construct pd.array([value]).","Check values.ndim before construction and reshape/ravel as needed."],"exampleFix":"# before\npd.arrays.NumpyExtensionArray(np.array(5))\n# after\npd.arrays.NumpyExtensionArray(np.array([5]))","handlingStrategy":"validation","validationCode":"import numpy as np\n\ndef ensure_1d_ndarray(values) -> np.ndarray:\n    arr = np.asarray(values)\n    if arr.ndim == 0:\n        arr = arr.reshape(1)\n    return arr","typeGuard":"import numpy as np\n\ndef is_1d_ndarray(values) -> bool:\n    return isinstance(values, np.ndarray) and values.ndim >= 1","tryCatchPattern":"try:\n    arr = pd.arrays.NumpyExtensionArray(values)\nexcept ValueError:\n    arr = pd.arrays.NumpyExtensionArray(np.atleast_1d(values))","preventionTips":["Validate arr.ndim >= 1 before wrapping in NumpyExtensionArray.","Use np.atleast_1d on scalar-derived inputs.","Remember ExtensionArrays are sequences, not scalar containers."],"tags":["numpy","constructor","dimension","pandas-arrays"],"analyzedSha":"71959b8cb9b2459c16e14b34f28b178ccfe14735","analyzedAt":"2026-08-07T01:30:20.476Z","schemaVersion":2},"datasetVersion":"2026-08-07T03:17:09.362Z"}