BUG: Fix 58807

doc/source/whatsnew/v3.0.0.rst

@@ -116,9 +116,18 @@ These improvements also fixed certain bugs in groupby:
 - :meth:`.DataFrameGroupBy.sum` would have incorrect values when there are multiple groupings, unobserved groups, and non-numeric data (:issue:`43891`)
 - :meth:`.DataFrameGroupBy.value_counts` would produce incorrect results when used with some categorical and some non-categorical groupings and ``observed=False`` (:issue:`56016`)
 
-.. _whatsnew_300.notable_bug_fixes.notable_bug_fix2:
+.. _whatsnew_300.notable_bug_fixes.improved_error_message_agg:
 
-notable_bug_fix2
+Improved error message for :meth:`DataFrame.agg`
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When :meth:`DataFrame.agg` is called with ``axis=1`` and a ``func`` which relabels the result index, the :func:`relabel_result` function iterates over result columns rather than the result rows, causing a confusing chain of ``KeyError`` exceptions (:issue:`58807`).
+
+This error is now handled in :func:`frame_apply` by throwing a ``NotImplementedError`` with a more explicit error message.
+
+.. _whatsnew_300.notable_bug_fixes.notable_bug_fix3:
+
+notable_bug_fix3
 ^^^^^^^^^^^^^^^^
 
 .. ---------------------------------------------------------------------------

pandas/core/apply.py

@@ -90,16 +90,20 @@ def frame_apply(
     kwargs=None,
 ) -> FrameApply:
     """construct and return a row or column based frame apply object"""
+    _, func, columns, _ = reconstruct_func(func, **kwargs)
+
     axis = obj._get_axis_number(axis)
     klass: type[FrameApply]
     if axis == 0:
         klass = FrameRowApply
     elif axis == 1:
+        if columns:
+            raise NotImplementedError(
+                "func given to frame_apply cannot contain "
+                "an index relabeling when axis is 1"
+            )
         klass = FrameColumnApply
 
-    _, func, _, _ = reconstruct_func(func, **kwargs)
-    assert func is not None
-
     return klass(
         obj,
         func,

pandas/core/shared_docs.py

@@ -49,6 +49,8 @@
 for more details.
 
 A passed user-defined-function will be passed a Series for evaluation.
+
+If `func` defines an index relabeling, `axis` must be `0` or `index`.
 {examples}"""
 
 _shared_docs["compare"] = """

pandas/tests/apply/test_frame_apply.py

@@ -1329,6 +1329,10 @@ def test_agg_reduce(axis, float_frame):
     expected = expected.T if axis in {1, "columns"} else expected
     tm.assert_frame_equal(result, expected)
 
+    msg = "func given to frame_apply cannot contain an index relabeling when axis is 1"
+    with pytest.raises(NotImplementedError, match=msg):
+        float_frame.agg(row1=(name1, "sum"), row2=(name2, "max"), axis=1)
+
 
 def test_nuiscance_columns():
     # GH 15015