{"record":{"id":"c792e6c47b1363c8","repo":"pandas-dev/pandas","slug":"axis-must-be-fewer-than-the-number-of-dimensions","errorCode":null,"errorMessage":"`axis` must be fewer than the number of dimensions ({ndim})","messagePattern":"`axis` must be fewer than the number of dimensions \\((.+?)\\)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"pandas/compat/numpy/function.py","lineNumber":363,"sourceCode":"\ndef validate_minmax_axis(axis: AxisInt | None, ndim: int = 1) -> None:\n    \"\"\"\n    Ensure that the axis argument passed to min, max, argmin, or argmax is zero\n    or None, as otherwise it will be incorrectly ignored.\n\n    Parameters\n    ----------\n    axis : int or None\n    ndim : int, default 1\n\n    Raises\n    ------\n    ValueError\n    \"\"\"\n    if axis is None:\n        return\n    if axis >= ndim or (axis < 0 and ndim + axis < 0):\n        raise ValueError(f\"`axis` must be fewer than the number of dimensions ({ndim})\")\n\n\n_validation_funcs = {\n    \"median\": validate_median,\n    \"mean\": validate_mean,\n    \"min\": validate_min,\n    \"max\": validate_max,\n    \"sum\": validate_sum,\n    \"prod\": validate_prod,\n}\n\n\ndef validate_func(fname: str, args: tuple[Any, ...], kwargs: dict[str, Any]) -> None:\n    if fname not in _validation_funcs:\n        return validate_stat_func(args, kwargs, fname=fname)\n\n    validation_func = _validation_funcs[fname]\n    return validation_func(args, kwargs)","sourceCodeStart":345,"sourceCodeEnd":381,"githubUrl":"https://github.com/pandas-dev/pandas/blob/3b7651241d4da534b3559b60ef128e1c34f54116/pandas/compat/numpy/function.py#L345-L381","documentation":"Raised by `validate_minmax_axis` when the `axis` argument to min/max/argmin/argmax on a Series or lower-dim object is out of range. Because pandas intentionally ignores invalid axis values for these methods, the validator surfaces the bug explicitly rather than silently returning the wrong result. The check fires when `axis >= ndim` or when the negative wrap (`ndim + axis`) is still negative.","triggerScenarios":"`s.argmax(axis=1)` on a Series (ndim=1); `s.min(axis=2)`; `df.min(axis=3)` on a 2D frame; `s.max(axis=-5)` where `-5 + 1 < 0`.","commonSituations":"Looping over axis as an integer and overshooting the object's dimensionality; refactoring code from DataFrame to Series without dropping the axis arg; off-by-one when computing axis dynamically.","solutions":["Drop the `axis` argument entirely for Series (axis 0 is the only valid value).","For DataFrames, ensure `axis` is 0 or 1 (or None).","Validate `0 <= axis < obj.ndim` before the call."],"exampleFix":"// before\ns = pd.Series([1, 2, 3])\ns.argmax(axis=1)\n\n// after\ns = pd.Series([1, 2, 3])\ns.argmax()","handlingStrategy":"validation","validationCode":"def valid_axis(axis, ndim):\n    return axis is None or (0 <= axis < ndim) or (-ndim <= axis < 0)","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Omit axis for Series reductions.","Compute axis from obj.ndim dynamically rather than hardcoding."],"tags":["numpy-compat","axis-validation","reductions"],"backgroundTag":null,"analyzedSha":"3b7651241d4da534b3559b60ef128e1c34f54116","analyzedAt":"2026-08-11T22:10:44.015Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}