{"record":{"id":"c5703b5894463540","repo":"pola-rs/polars","slug":"use-of-how-outer-coalesce-should-be-replaced-w","errorCode":null,"errorMessage":"use of `how='outer_coalesce'` should be replaced with `how='full', coalesce=True`.","messagePattern":"use of `how='outer_coalesce'` should be replaced with `how='full', coalesce=True`\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/lazyframe/frame.py","lineNumber":6107,"sourceCode":"        require_same_type(self, other)\n\n        if maintain_order is None:\n            maintain_order = \"none\"\n\n        uses_on = on is not None\n        uses_left_on = left_on is not None\n        uses_right_on = right_on is not None\n        uses_lr_on = uses_left_on or uses_right_on\n        if uses_on and uses_lr_on:\n            msg = \"cannot use 'on' in conjunction with 'left_on' or 'right_on'\"\n            raise ValueError(msg)\n        elif uses_left_on != uses_right_on:\n            msg = \"'left_on' requires corresponding 'right_on'\"\n            raise ValueError(msg)\n\n        if how == \"outer\":  # type: ignore[comparison-overlap]\n            msg = \"use of `how='outer'` should be replaced with `how='full'`.\"\n            raise ValueError(msg)\n        elif how == \"outer_coalesce\":  # type: ignore[comparison-overlap]\n            msg = \"use of `how='outer_coalesce'` should be replaced with `how='full', coalesce=True`.\"\n            raise ValueError(msg)\n        elif how == \"cross\":\n            if uses_on or uses_lr_on:\n                msg = \"cross join should not pass join keys\"\n                raise ValueError(msg)\n            return self._from_pyldf(\n                self._ldf.join(\n                    other._ldf,\n                    [],\n                    [],\n                    allow_parallel,\n                    force_parallel,\n                    nulls_equal,\n                    how,\n                    suffix,\n                    validate,","sourceCodeStart":6089,"sourceCodeEnd":6125,"githubUrl":"https://github.com/pola-rs/polars/blob/68506541d2de983056c9eb244e1ea05fab377dfc/py-polars/src/polars/lazyframe/frame.py#L6089-L6125","documentation":"ValueError raised by LazyFrame.join when how='outer_coalesce' is passed. The old outer join variants were consolidated: 'outer' became 'full' and 'outer_coalesce' became how='full' with coalesce=True, so the legacy value is rejected with an explicit migration message.","triggerScenarios":"df1.join(df2, on='key', how='outer_coalesce') — legacy join syntax after a polars upgrade.","commonSituations":"Old notebooks, tutorials, or production queries written before the join-API rename; code generators emitting the historical how values.","solutions":["Use how='full', coalesce=True","For plain outer joins use how='full' (default coalesce behavior)","Grep the codebase for 'outer_coalesce' and 'how=\"outer\"' during upgrades"],"exampleFix":"# before\nlf1.join(lf2, on='id', how='outer_coalesce')\n# after\nlf1.join(lf2, on='id', how='full', coalesce=True)","handlingStrategy":"validation","validationCode":"if how == 'outer_coalesce':\n    how, coalesce = 'full', True\nelif how == 'outer':\n    how = 'full'","typeGuard":"def valid_join_how(h: object) -> bool:\n    return h in {'inner', 'left', 'full', 'semi', 'anti', 'cross', 'outer'}","tryCatchPattern":null,"preventionTips":["Adopt 'full' immediately on upgrade","Centralize join-how constants in one module","Grep for legacy how values when bumping polars"],"tags":["python","polars","join","migration","invalid-argument"],"backgroundTag":"api-behavior-change","analyzedSha":"68506541d2de983056c9eb244e1ea05fab377dfc","analyzedAt":"2026-08-28T18:02:35.179Z","contentChangedAt":"2026-08-28T18:02:35.179Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}