{"record":{"id":"de7be14cd65ac312","repo":"pandas-dev/pandas","slug":"axis-axis-is-out-of-bounds-for-array-of-dimensio","errorCode":null,"errorMessage":"axis {axis} is out of bounds for array of dimension {first.ndim}","messagePattern":"axis (.+?) is out of bounds for array of dimension (.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"pandas/core/arrays/categorical.py","lineNumber":2692,"sourceCode":"        codes = self.codes.copy()\n        mask = self.isna()\n        if func == np.minimum.accumulate:\n            codes[mask] = np.iinfo(codes.dtype.type).max\n        # no need to change codes for maximum because codes[mask] is already -1\n        if not skipna:\n            mask = np.maximum.accumulate(mask)\n\n        codes = func(codes)\n        codes[mask] = -1\n        return self._simple_new(codes, dtype=self._dtype)\n\n    @classmethod\n    def _concat_same_type(cls, to_concat: Sequence[Self], axis: AxisInt = 0) -> Self:\n        from pandas.core.dtypes.concat import union_categoricals\n\n        first = to_concat[0]\n        if axis >= first.ndim:\n            raise ValueError(\n                f\"axis {axis} is out of bounds for array of dimension {first.ndim}\"\n            )\n\n        if axis == 1:\n            # Flatten, concatenate then reshape\n            if not all(x.ndim == 2 for x in to_concat):\n                raise ValueError\n\n            # pass correctly-shaped to union_categoricals\n            tc_flat = []\n            for obj in to_concat:\n                tc_flat.extend([obj[:, i] for i in range(obj.shape[1])])\n\n            res_flat = cls._concat_same_type(tc_flat, axis=0)\n\n            result = res_flat.reshape(len(first), -1, order=\"F\")\n            return result\n","sourceCodeStart":2674,"sourceCodeEnd":2710,"githubUrl":"https://github.com/pandas-dev/pandas/blob/3b7651241d4da534b3559b60ef128e1c34f54116/pandas/core/arrays/categorical.py#L2674-L2710","documentation":"Raised in Categorical._concat_same_type when the axis argument is greater than or equal to the number of dimensions of the categorical arrays being concatenated. A 1-D categorical only has axis 0; passing axis=1 is out of bounds. The guard exists because concat dispatch may pass an axis meant for 2-D ExtensionArray stacking.","triggerScenarios":"pd.concat([cat1, cat2], axis=1) routing through _concat_same_type on 1-D categoricals. Internal 2-D reshape path where the input was unexpectedly 1-D. Calling Categorical._concat_same_type directly with axis>=ndim.","commonSituations":"Concatenating Series along axis=1 to form a DataFrame where the block consolidation path hits categorical concatenation with the wrong axis. Building a DataFrame column-by-column with categoricals under a code path that forwards axis=1 to the EA-level concat.","solutions":["Confirm the intended axis: 1-D categoricals concatenate along axis=0.","Use pd.concat([s1, s2], axis=1) at the Series level rather than calling EA concat directly.","Ensure inputs are 2-D if you genuinely need axis=1 (e.g., stack into a 2-D array first).","Check that to_concat elements are not accidentally squeezed to 1-D before the call."],"exampleFix":"# before (illustrative of the internal guard)\nc1 = pd.Categorical(['a','b'])\nc2 = pd.Categorical(['c','d'])\npd.Categorical._concat_same_type([c1, c2], axis=1)  # ValueError\n\n# after\npd.Categorical._concat_same_type([c1, c2], axis=0)","handlingStrategy":"validation","validationCode":"if axis >= to_concat[0].ndim:\n    raise ValueError(f'axis {axis} out of range for {to_concat[0].ndim}-D arrays')\nresult = pd.Categorical._concat_same_type(to_concat, axis=axis)","typeGuard":"def valid_axis_for_concat(axis: int, arrays) -> bool:\n    return 0 <= axis < min(a.ndim for a in arrays)","tryCatchPattern":"try:\n    out = pd.Categorical._concat_same_type(parts, axis=axis)\nexcept ValueError as e:\n    if 'out of bounds' in str(e):\n        out = pd.Categorical._concat_same_type(parts, axis=0)\n    else:\n        raise","preventionTips":["Prefer pd.concat at the Series/DataFrame level; do not call EA concat directly.","When stacking 2-D, verify each element is 2-D before passing axis=1."],"tags":["categorical","concat","axis","dimensionality"],"backgroundTag":null,"analyzedSha":"3b7651241d4da534b3559b60ef128e1c34f54116","analyzedAt":"2026-08-11T22:10:44.015Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}