pola-rs/polars · error · ValueError

use of `how='outer'` should be replaced with `how='full'`.

Error message

use of `how='outer'` should be replaced with `how='full'`.

What it means

Deprecation/removal guard in LazyFrame.join: 'outer' is the old name for the full outer join. polaris renamed the strategy to 'full' (because 'outer' was ambiguous across ecosystems), so passing how='outer' is intercepted after the on/left_on/right_on consistency checks and rejected with a pointer to the replacement.

Solutions

1. Replace how='outer' with how='full'
2. If old behavior also dropped/coalesced keys, consider how='full', coalesce=True
3. Update any wrapper functions that pass join strategy through as a variable

Example fix

// before
df.join(other, on='id', how='outer')
// after
df.join(other, on='id', how='full')

def safe_join(df, other, how, **kw):
    if how == 'outer':
        how = 'full'
    return df.join(other, how=how, **kw)

def is_valid_join_strategy(how) -> bool:
    return how not in ('outer', 'outer_coalesce')

try:
    out = df.join(other, on='id', how=how)
except ValueError as e:
    if "how='outer'" in str(e):
        out = df.join(other, on='id', how='full')
    else:
        raise

When it happens

Trigger: Calling lf.join(other, on='id', how='outer') on a Polars version where 'outer' was removed in favor of 'full' (Polars 1.0 renamed outer to full).

Common situations: Upgrading Polars after code written against pre-1.0 API; tutorials or Stack Overflow snippets using the old name; porting pandas-style 'outer' merge vocabulary.

Understand the failure class

Background: "is deprecated and will be removed" — deprecation warnings for old API names, keywords, and options, and how to migrate before the removal release — this error's family across 29 libraries.

Related errors

• use of `how='outer_coalesce'` should be replaced with…
• accessing ` ` from the top-level `polars` module was…
• cannot use 'on' in conjunction with 'left_on' or 'right_on'
• cross join should not pass join keys
• `how` must be one of

AI-assisted analysis of pola-rs/polars@fe841f959e (2026-09-18). Data as JSON: /api/errors/088e53503729ee8c. Report an issue: GitHub.

Appendix: source

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

        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,
                    maintain_order,
                    build_side=build_side,
                    coalesce=None,
                )
            )

        if uses_on:

View on GitHub (pinned to fe841f959e)