pola-rs/polars · error · ValueError

`how` must be one of {'left', 'inner', 'full'}; found {how!r

Error message

`how` must be one of {'left', 'inner', 'full'}; found {how!r}

What it means

LazyFrame.update overwrites values in self from `other` via a join; only 'left', 'inner', and 'full' matching strategies exist for updates. Any other `how` raises ValueError. 'outer'/'outer_coalesce' are accepted but deprecated (remapped to 'full' with a DeprecationWarning since polars 0.20.29).

Source

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

        ╞═════╪══════╡
        │ 1   ┆ -99  │
        │ 2   ┆ 500  │
        │ 3   ┆ null │
        │ 4   ┆ 700  │
        │ 5   ┆ -66  │
        └─────┴──────┘
        """
        require_same_type(self, other)
        if how in ("outer", "outer_coalesce"):
            how = "full"
            issue_deprecation_warning(
                "use of `how='outer'` should be replaced with `how='full'`.",
                version="0.20.29",
            )

        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)
                if right_on is None:
                    msg = "missing join columns for right frame"
                    raise ValueError(msg)
        else:

View on GitHub (pinned to df599052da)

Solutions

1. Use one of 'left', 'inner', or 'full'
2. Replace deprecated how='outer' with how='full' to also silence the DeprecationWarning
3. For a right-side perspective, swap the frames: other.update(lf, ...) instead of how='right'

Example fix

// before
lf.update(other, on='id', how='right')

// after
other.update(lf, on='id', how='left')  # right-update expressed from the other side

valid = {'left', 'inner', 'full'}
if how in ('outer', 'outer_coalesce'):
    how = 'full'
if how not in valid:
    raise ValueError(f'update strategy must be one of {valid}, got {how!r}')

When it happens

Trigger: lf.update(other, on='id', how='right'), how='cross', how='semi', or any join-style strategy not in {'left','inner','full'}; copying a `how` value that is valid for LazyFrame.join into update.

Common situations: Porting join() code to update(); assuming join and update share the same strategy vocabulary; keeping how='outer' after a polars upgrade.

Related errors

• missing join columns for left frame
• missing join columns for right frame
• left join column {name!r} not found
• right join column {name!r} not found
• expected `other` to be a {qualified_type_name(current)!r}, n

AI-assisted analysis of pola-rs/polars@df599052da (2026-08-16). Data as JSON: /api/errors/af5659d46e515b39. Report an issue: GitHub.