{"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/3b7651241d4da534b3559b60ef128e1c34f54116/pandas/core/arrays/numpy_.py#L116-L152","documentation":"Raised by NumpyExtensionArray.__init__ when values.ndim == 0 (a scalar 0-dimensional ndarray). NumpyExtensionArray is documented as 1-dimensional; a 0-D input has no length and cannot back an ExtensionArray. (2-D is technically accepted but not advertised, per the inline comment.) The check is on ndim==0 specifically.","triggerScenarios":"pd.arrays.NumpyExtensionArray(np.array(5)) — np.array(5) is 0-D. Passing the result of np.asarray(scalar) or np.float64(1.0). Extracting a scalar via .item()-like ops and feeding it back.","commonSituations":"Code that indexes a single element and keeps it as a 0-D array (e.g. arr[arr > 0].sum() shape) then tries to wrap it; arithmetic producing a scalar numpy value.","solutions":["Wrap the scalar in a 1-element 1-D array: np.atleast_1d(np.asarray(value)).","Use np.array([value]) explicitly to get a 1-D length-1 array.","Reconsider whether an ExtensionArray is the right container for a single scalar."],"exampleFix":"# before\npd.arrays.NumpyExtensionArray(np.array(5))  # raises (0-D)\n\n# after\npd.arrays.NumpyExtensionArray(np.atleast_1d(np.array(5)))","handlingStrategy":"validation","validationCode":"import numpy as np\n\ndef to_1d_numpy_extension_array(values):\n    arr = np.asarray(values)\n    if arr.ndim == 0:\n        arr = np.atleast_1d(arr)\n    return pd.arrays.NumpyExtensionArray(arr)","typeGuard":"import numpy as np\n\ndef is_nonzero_nd(obj) -> bool:\n    return hasattr(obj, 'ndim') and obj.ndim >= 1","tryCatchPattern":"try:\n    pd.arrays.NumpyExtensionArray(values)\nexcept ValueError as e:\n    if '1-dimensional' in str(e):\n        pd.arrays.NumpyExtensionArray(np.atleast_1d(np.asarray(values)))\n    else:\n        raise","preventionTips":["Wrap scalars with np.atleast_1d() or np.array([value]) before construction.","Check .ndim on results of reductions (sum/mean) before re-wrapping.","Use pd.array(value) which handles scalar-to-1-D promotion."],"tags":["pandas","numpy-extension-array","constructor","shape","scalar"],"backgroundTag":null,"analyzedSha":"3b7651241d4da534b3559b60ef128e1c34f54116","analyzedAt":"2026-08-11T22:10:44.015Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}