pandas-dev/pandas · error · ValueError

by_row={by_row} not allowed

Error message

by_row={by_row} not allowed

What it means

Raised by `FrameApply.__init__` when `by_row` is passed a value other than `False` or the literal `'compat'`. `by_row` is a narrow internal-compatible flag for DataFrame.apply; users essentially never set it directly, and only those two values are valid for the frame variant (SeriesApply accepts an additional '_compat').

Source

Thrown at pandas/core/apply.py:932

class FrameApply(NDFrameApply):
    obj: DataFrame

    def __init__(
        self,
        obj: AggObjType,
        func: AggFuncType,
        raw: bool,
        result_type: str | None,
        *,
        by_row: Literal[False, "compat"] = False,
        engine: str = "python",
        engine_kwargs: dict[str, bool] | None = None,
        args,
        kwargs,
    ) -> None:
        if by_row is not False and by_row != "compat":
            raise ValueError(f"by_row={by_row} not allowed")
        super().__init__(
            obj,
            func,
            raw,
            result_type,
            by_row=by_row,
            engine=engine,
            engine_kwargs=engine_kwargs,
            args=args,
            kwargs=kwargs,
        )

    # ---------------------------------------------------------------
    # Abstract Methods

    @property
    @abc.abstractmethod
    def result_index(self) -> Index:

View on GitHub (pinned to 71959b8cb9)

Solutions

1. Omit `by_row` entirely for normal DataFrame.apply usage.
2. If you must pass it, use exactly `False` or `'compat'`.
3. Audit where the unsupported `by_row` value originates (often a forwarded kwargs dict).

Example fix

# before
df.apply(my_func, by_row=True)
# after
df.apply(my_func)
# or explicitly
df.apply(my_func, by_row='compat')

def safe_frame_apply(df, func, by_row=None, **kw):
    if by_row is not None and by_row not in (False, 'compat'):
        raise ValueError(f"by_row must be False or 'compat', got {by_row!r}")
    return df.apply(func) if by_row is None else df.apply(func, by_row=by_row)

def is_valid_frame_by_row(v) -> bool:
    return v in (False, 'compat', None)

try:
    df.apply(func, by_row=v)
except ValueError as e:
    if 'by_row' in str(e):
        df.apply(func)  # drop by_row
    else:
        raise

When it happens

Trigger: Calling `df.apply(func, by_row=True)` or `df.apply(func, by_row='something')`. Most user-facing code does not pass `by_row` at all; this error indicates the kwarg was set explicitly with an unsupported value.

Common situations: Code intended for Series.apply (which has different by_row semantics) reused on a DataFrame; experimental use of the by_row flag without reading its contract; library code that forwards arbitrary kwargs into apply.

Related errors

• invalid value for result_type, must be one of {None, 'reduce
• No transform functions were provided
• cannot perform both aggregation and transformation operation
• Operation {func} does not support axis=1
• Label(s) {list(cols)} do not exist

AI-assisted analysis of pandas-dev/pandas@71959b8cb9 (2026-08-07). Data as JSON: /api/errors/adf08763ac53470d. Report an issue: GitHub.