{"record":{"id":"f98fdb3b63ad5c36","repo":"pandas-dev/pandas","slug":"mask-must-be-a-1d-list-like","errorCode":null,"errorMessage":"mask must be a 1D list-like","messagePattern":"mask must be a 1D list-like","errorType":"exception","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"pandas/core/arrays/numeric.py","lineNumber":215,"sourceCode":"            if is_nan_na():\n                mask = np.isnan(values)\n            else:\n                mask = np.zeros(len(values), dtype=np.bool_)\n                if dtype_cls.__name__.strip(\"_\").startswith((\"I\", \"U\")):\n                    wrong = np.isnan(values)\n                    if wrong.any():\n                        raise ValueError(\"Cannot cast NaN value to Integer dtype.\")\n        elif is_nan_na():\n            mask = libmissing.is_numeric_na(values)\n        else:\n            # is_numeric_na will raise on non-numeric NAs\n            libmissing.is_numeric_na(values)\n            mask = libmissing.is_pdna_or_none(values)\n    else:\n        assert len(mask) == len(values)\n\n    if mask.ndim != 1:\n        raise TypeError(\"mask must be a 1D list-like\")\n\n    # infer dtype if needed\n    if dtype is None:\n        dtype = default_dtype\n    else:\n        dtype = dtype.numpy_dtype\n\n    if is_integer_dtype(dtype) and values.dtype.kind == \"f\" and len(values) > 0:\n        if mask.all():\n            values = np.ones(values.shape, dtype=dtype)\n        else:\n            idx = np.nanargmax(values)\n            if int(values[idx]) != original[idx]:\n                # We have ints that lost precision during the cast.\n                inferred_type = lib.infer_dtype(original, skipna=True)\n                if (\n                    inferred_type not in [\"floating\", \"mixed-integer-float\"]\n                    and not mask.any()","sourceCodeStart":197,"sourceCodeEnd":233,"githubUrl":"https://github.com/pandas-dev/pandas/blob/3b7651241d4da534b3559b60ef128e1c34f54116/pandas/core/arrays/numeric.py#L197-L233","documentation":"Raised by _coerce_to_data_and_mask when the mask passed alongside values has mask.ndim != 1. The mask is normally only supplied via the internal fast-path that splits an existing masked array into _data/_mask, both of which are 1-D. A non-1-D mask indicates an internal/caller contract violation: the mask must be a flat boolean array matching the length of values.","triggerScenarios":"Internally: extracting _data/_mask from a higher-dimensional masked array (rare; the values.ndim check at line 188 usually fires first). Direct: calling NumericArray(data, mask) with a 2-D mask ndarray. Subclass code that synthesizes a mask of the wrong shape.","commonSituations":"Almost always an internal/library bug or a subclass overriding construction with a mis-shaped mask; end users rarely hit it because the public API never accepts a mask argument.","solutions":["Ensure the mask is 1-D: mask = np.asarray(mask).ravel() and confirm len(mask) == len(values).","If you are subclassing NumericArray, recompute the mask via the standard _coerce_to_data_and_mask path instead of constructing it manually.","Report as a pandas bug if reached through the public API without a custom mask."],"exampleFix":"# before (internal)\nmask = np.zeros((3, 2), dtype=bool)  # 2-D\narr = IntegerArray(values, mask)        # raises\n\n# after\nmask = np.zeros(values.shape[0], dtype=bool)  # 1-D","handlingStrategy":"validation","validationCode":"import numpy as np\n\ndef assert_valid_mask(values, mask):\n    mask = np.asarray(mask, dtype=bool)\n    assert mask.ndim == 1, 'mask must be 1-D'\n    assert mask.shape[0] == values.shape[0], 'mask length mismatch'\n    return mask","typeGuard":"def is_flat_bool_mask(mask, values) -> bool:\n    import numpy as np\n    m = np.asarray(mask)\n    return m.ndim == 1 and m.dtype == bool and m.shape[0] == np.asarray(values).shape[0]","tryCatchPattern":"try:\n    NumericArray(values, mask)\nexcept TypeError as e:\n    if 'mask must be a 1D' in str(e):\n        mask = np.asarray(mask, dtype=bool).ravel()\n        NumericArray(values, mask)\n    else:\n        raise","preventionTips":["Never pass a custom mask to NumericArray from user code; use pd.array().","In subclasses, always derive the mask from the standard _coerce_to_data_and_mask path.","If synthesizing a mask, assert ndim==1 and length match before construction."],"tags":["pandas","masked-array","numeric","mask","shape","internal"],"backgroundTag":null,"analyzedSha":"3b7651241d4da534b3559b60ef128e1c34f54116","analyzedAt":"2026-08-11T22:10:44.015Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}