pola-rs/polars · error · ValueError

use of `how='outer_coalesce'` should be replaced with `how='

Error message

use of `how='outer_coalesce'` should be replaced with `how='full', coalesce=True`.

What it means

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.

Source

Thrown at py-polars/src/polars/lazyframe/frame.py:6107

        require_same_type(self, other)

        if maintain_order is None:
            maintain_order = "none"

        uses_on = on is not None
        uses_left_on = left_on is not None
        uses_right_on = right_on is not None
        uses_lr_on = uses_left_on or uses_right_on
        if uses_on and uses_lr_on:
            msg = "cannot use 'on' in conjunction with 'left_on' or 'right_on'"
            raise ValueError(msg)
        elif uses_left_on != uses_right_on:
            msg = "'left_on' requires corresponding 'right_on'"
            raise ValueError(msg)

        if how == "outer":  # type: ignore[comparison-overlap]
            msg = "use of `how='outer'` should be replaced with `how='full'`."
            raise ValueError(msg)
        elif how == "outer_coalesce":  # type: ignore[comparison-overlap]
            msg = "use of `how='outer_coalesce'` should be replaced with `how='full', coalesce=True`."
            raise ValueError(msg)
        elif how == "cross":
            if uses_on or uses_lr_on:
                msg = "cross join should not pass join keys"
                raise ValueError(msg)
            return self._from_pyldf(
                self._ldf.join(
                    other._ldf,
                    [],
                    [],
                    allow_parallel,
                    force_parallel,
                    nulls_equal,
                    how,
                    suffix,
                    validate,

View on GitHub (pinned to 68506541d2)

Solutions

1. Use how='full', coalesce=True
2. For plain outer joins use how='full' (default coalesce behavior)
3. Grep the codebase for 'outer_coalesce' and 'how="outer"' during upgrades

Example fix

# before
lf1.join(lf2, on='id', how='outer_coalesce')
# after
lf1.join(lf2, on='id', how='full', coalesce=True)

if how == 'outer_coalesce':
    how, coalesce = 'full', True
elif how == 'outer':
    how = 'full'

def valid_join_how(h: object) -> bool:
    return h in {'inner', 'left', 'full', 'semi', 'anti', 'cross', 'outer'}

When it happens

Trigger: df1.join(df2, on='key', how='outer_coalesce') — legacy join syntax after a polars upgrade.

Common situations: Old notebooks, tutorials, or production queries written before the join-API rename; code generators emitting the historical how values.

Related errors

• `{name}` was removed in version {version}
• {func_name!r} received both {param.name!r} and {param.new_na
• the argument {param.name!r} for {func_name!r}{was_deprecated
• the argument {param.name!r} for {func_name!r}{was_deprecated
• `strict=False` is no longer supported for `how='horizontal'`

AI-assisted analysis of pola-rs/polars@68506541d2 (2026-08-28). Data as JSON: /api/errors/c5703b5894463540. Report an issue: GitHub.