{"record":{"id":"efdcf192cd8e04ee","repo":"pandas-dev/pandas","slug":"transform-function-failed","errorCode":null,"errorMessage":"Transform function failed","messagePattern":"Transform function failed","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"pandas/core/apply.py","lineNumber":393,"sourceCode":"                )\n            # Convert func equivalent dict\n            if is_series:\n                func = {com.get_callable_name(v) or v: v for v in func}\n            else:\n                func = dict.fromkeys(obj, func)\n\n        if is_dict_like(func):\n            func = cast(\"AggFuncTypeDict\", func)\n            return self.transform_dict_like(func)\n\n        # func is either str or callable\n        func = cast(\"AggFuncTypeBase\", func)\n        try:\n            result = self.transform_str_or_callable(func)\n        except TypeError:\n            raise\n        except Exception as err:\n            raise ValueError(\"Transform function failed\") from err\n\n        # Functions that transform may return empty Series/DataFrame\n        # when the dtype is not appropriate\n        if (\n            isinstance(result, (ABCSeries, ABCDataFrame))\n            and result.empty\n            and not obj.empty\n        ):\n            raise ValueError(\"Transform function failed\")\n        if not isinstance(result, (ABCSeries, ABCDataFrame)) or not result.index.equals(\n            obj.index\n        ):\n            raise ValueError(\"Function did not transform\")\n\n        return result\n\n    def transform_dict_like(self, func) -> DataFrame:\n        \"\"\"","sourceCodeStart":375,"sourceCodeEnd":411,"githubUrl":"https://github.com/pandas-dev/pandas/blob/3b7651241d4da534b3559b60ef128e1c34f54116/pandas/core/apply.py#L375-L411","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Debug the actual exception by catching it directly: temporarily replace transform with apply to see the real error.","Ensure your function returns a same-shaped result: for transform, use vectorized operations that preserve length, not reductions.","If the function fails on specific dtypes, filter columns or convert dtypes before transforming.","Use a try/except inside your function to handle per-column failures gracefully."],"exampleFix":"# before — sum returns scalar, not same-shaped array\ndf.transform(lambda x: x.sum())\n\n# after — use a valid transform (same length output)\ndf.transform(lambda x: x - x.mean())\n# or use agg if you want reduction\ndf.agg(lambda x: x.sum())","handlingStrategy":"try-catch","validationCode":"def validate_transform_func(series, func):\n    \"\"\"Test func on a small sample to verify it produces same-length output.\"\"\"\n    sample = series.head(2)\n    result = func(sample)\n    if len(result) != len(sample):\n        raise ValueError(f\"Function does not produce same-length output required by transform\")\n    return True","typeGuard":null,"tryCatchPattern":"try:\n    result = df.transform(func)\nexcept ValueError as e:\n    if \"Transform function failed\" in str(e):\n        # switch to agg if the function is a reduction\n        result = df.agg(func)\n    else:\n        raise","preventionTips":["Ensure transform functions always return same-length output — use vectorized operations, not reductions.","Test your function on a small sample with apply first to see the real error.","Remember: transform preserves shape, agg reduces — use the right one.","Filter columns by dtype before transform if the function only works on specific types."],"tags":["pandas","transform","function-failure","shape-mismatch","valueerror"],"backgroundTag":null,"analyzedSha":"3b7651241d4da534b3559b60ef128e1c34f54116","analyzedAt":"2026-08-11T22:10:44.015Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}