pandas-dev/pandas · error · ValueError

Transform function failed

Error message

Transform function failed

What it means

When transform() calls the user-provided function and it raises any exception other than TypeError (which is re-raised as-is), pandas wraps it in a ValueError with the generic message 'Transform function failed'. This is because transform has a strict contract: the function must return a result with the same shape as the input. The wrapping distinguishes transform failures from aggregation failures and signals that the function is incompatible with transform semantics.

Solutions

1. Debug the actual exception by catching it directly: temporarily replace transform with apply to see the real error.
2. Ensure your function returns a same-shaped result: for transform, use vectorized operations that preserve length, not reductions.
3. If the function fails on specific dtypes, filter columns or convert dtypes before transforming.
4. Use a try/except inside your function to handle per-column failures gracefully.

Example fix

# before — sum returns scalar, not same-shaped array
df.transform(lambda x: x.sum())

# after — use a valid transform (same length output)
df.transform(lambda x: x - x.mean())
# or use agg if you want reduction
df.agg(lambda x: x.sum())

def validate_transform_func(series, func):
    """Test func on a small sample to verify it produces same-length output."""
    sample = series.head(2)
    result = func(sample)
    if len(result) != len(sample):
        raise ValueError(f"Function does not produce same-length output required by transform")
    return True

try:
    result = df.transform(func)
except ValueError as e:
    if "Transform function failed" in str(e):
        # switch to agg if the function is a reduction
        result = df.agg(func)
    else:
        raise

When it happens

Trigger: Calling df.transform(func) where func raises an exception internally — e.g., a KeyError from column access, a ZeroDivisionError, an AttributeError, or any other non-TypeError exception. The function may work for some columns but fail for others (e.g., calling .str method on numeric data).

Common situations: Using a function designed for aggregation (e.g., lambda x: x.sum()) in a transform context — it returns a scalar, which triggers a shape check failure. Functions that depend on a specific dtype failing on mixed-type DataFrames. Functions that reference column names that don't exist in all groups.

Related errors

• Function did not transform
• cannot combine transform and aggregation operations
• No transform functions were provided
• too many dims to broadcast
• by_row= not allowed

AI-assisted analysis of pandas-dev/pandas@3b7651241d (2026-08-11). Data as JSON: /api/errors/efdcf192cd8e04ee. Report an issue: GitHub.

Appendix: source

Thrown at pandas/core/apply.py:393

                )
            # Convert func equivalent dict
            if is_series:
                func = {com.get_callable_name(v) or v: v for v in func}
            else:
                func = dict.fromkeys(obj, func)

        if is_dict_like(func):
            func = cast("AggFuncTypeDict", func)
            return self.transform_dict_like(func)

        # func is either str or callable
        func = cast("AggFuncTypeBase", func)
        try:
            result = self.transform_str_or_callable(func)
        except TypeError:
            raise
        except Exception as err:
            raise ValueError("Transform function failed") from err

        # Functions that transform may return empty Series/DataFrame
        # when the dtype is not appropriate
        if (
            isinstance(result, (ABCSeries, ABCDataFrame))
            and result.empty
            and not obj.empty
        ):
            raise ValueError("Transform function failed")
        if not isinstance(result, (ABCSeries, ABCDataFrame)) or not result.index.equals(
            obj.index
        ):
            raise ValueError("Function did not transform")

        return result

    def transform_dict_like(self, func) -> DataFrame:
        """

View on GitHub (pinned to 3b7651241d)