pola-rs/polars · error · ValueError

missing join columns for right frame

Error message

missing join columns for right frame

What it means

Mirror of the left-frame case: in LazyFrame.update with `on` None, if `left_on` is given but `right_on` is None, the right frame's key columns are unknown and ValueError('missing join columns for right frame') is raised.

Source

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

            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:
            # move on into left/right_on to simplify logic
            left_on = right_on = on

        if isinstance(left_on, str):
            left_on = [left_on]
        if isinstance(right_on, str):
            right_on = [right_on]

        left_schema = self.collect_schema()
        for name in left_on:
            if name not in left_schema:
                msg = f"left join column {name!r} not found"
                raise ValueError(msg)
        right_schema = other.collect_schema()
        for name in right_on:
            if name not in right_schema:
                msg = f"right join column {name!r} not found"

View on GitHub (pinned to df599052da)

Solutions

1. Provide both: lf.update(other, left_on='key_l', right_on='key_r')
2. Or use `on='key'` when key names match
3. Add a pre-call assertion in shared code that left_on/right_on are both set or both None

Example fix

// before
lf.update(other, left_on='key_l')

// after
lf.update(other, left_on='key_l', right_on='key_r')

if on is None and ((left_on is None) != (right_on is None)):
    raise ValueError('update needs `on`, or both `left_on` and `right_on`')

When it happens

Trigger: lf.update(other, left_on='key_l') with neither `on` nor `right_on`; programmatic calls that build kwargs and skip right_on.

Common situations: Half-finished refactors of join calls; key-mapping dicts that only define the left side.

Related errors

• missing join columns for left frame
• 'left_on' requires corresponding 'right_on'
• must specify `on` OR `left_on` and `right_on`
• `how` must be one of {'left', 'inner', 'full'}; found {how!r
• left join column {name!r} not found

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