pola-rs/polars · error · ValueError

missing join columns for left frame

Error message

missing join columns for left frame

What it means

In LazyFrame.update, when `on` is None you must specify the join keys via BOTH `left_on` and `right_on`. If only `right_on` is given, the left frame's key columns are unknown, so ValueError('missing join columns for left frame') is raised.

Source

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

            )

        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:
            # 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()

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 the key name is identical in both frames
  3. Audit shared helper code that conditionally passes only one of left_on/right_on

Example fix

// before
lf.update(other, right_on='key_r')

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

Strategy: validation

Validate before calling

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`'
    )

Prevention

When it happens

Trigger: lf.update(other, right_on='key') with neither `on` nor `left_on`; passing left_on=None explicitly while right_on is set (e.g. a half-refactored call).

Common situations: Renaming key arguments when frames use different key names and forgetting the counterpart; refactoring a join(left_on=..., right_on=...) call into update() and dropping one side.

Related errors

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