pola-rs/polars · error · ValueError

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

Error message

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

What it means

Join-method guard catching both legacy outer strategies at once: how values 'outer' and 'outer_coalesce' were renamed. They now map to how='full' (with coalescing expressed via the coalesce parameter), so either old value fails the membership check against ('left', 'inner', 'full') and is rejected before the join is planned.

Solutions

1. Replace `how="outer"` with `how="full"`.
2. Replace `how="outer_coalesce"` with `how="full"` plus key coalescing if that behavior is desired.
3. Grep for `how="outer"` across the codebase and update all call sites.

Example fix

// before
lf.join(other, on="id", how="outer")
// after
lf.join(other, on="id", how="full")

if how in {"outer", "outer_coalesce"}:
    how = "full"
if how not in ("left", "inner", "full"):
    raise ValueError(f"unsupported how={how!r}")
out = lf.join(other, on="id", how=how)

try:
    out = lf.join(other, on=key, how=how)
except ValueError as e:
    if "should be replaced with" in str(e):
        out = lf.join(other, on=key, how="full")
    else:
        raise

When it happens

Trigger: Calling `lf.join(other, on="id", how="outer")` or `how="outer_coalesce"` — the membership check raises immediately.

Common situations: Migrating from polars < 1.0 where 'outer' was valid; copying join examples from older documentation or Stack Overflow answers.

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 `aggregate_function='count'` should be replaced with…
• cannot use 'on' in conjunction with 'left_on' or 'right_on'
• collect() got an unexpected keyword argument
• 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/42318e6ef6b9c806. Report an issue: GitHub.

Appendix: source

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

        ... ).collect()
        shape: (5, 2)
        ┌─────┬──────┐
        │ A   ┆ B    │
        │ --- ┆ ---  │
        │ i64 ┆ i64  │
        ╞═════╪══════╡
        │ 1   ┆ -99  │
        │ 2   ┆ 500  │
        │ 3   ┆ null │
        │ 4   ┆ 700  │
        │ 5   ┆ -66  │
        └─────┴──────┘
        """
        require_same_type(self, other)

        if how in {"outer", "outer_coalesce"}:  # type: ignore[comparison-overlap]
            msg = f"use of `how='{how}'` should be replaced with `how='full'`."
            raise ValueError(msg)

        if how not in ("left", "inner", "full"):
            msg = f"`how` must be one of {{'left', 'inner', 'full'}}; found {how!r}"
            raise ValueError(msg)

        row_index_name = None
        if on is None:
            if left_on is None and right_on is None:
                # no keys provided--use row index
                row_index_name = "__POLARS_ROW_INDEX"
                self = self.with_row_index(row_index_name)
                other = other.with_row_index(row_index_name)
                left_on = right_on = [row_index_name]
            else:
                # one of left or right is missing, raise error
                if left_on is None:
                    msg = "missing join columns for left frame"
                    raise ValueError(msg)

View on GitHub (pinned to fe841f959e)