pola-rs/polars · error · ValueError

left join column {name!r} not found

Error message

left join column {name!r} not found

What it means

Before joining, LazyFrame.update resolves self.collect_schema() and validates every name in left_on (or `on`) against it. An unknown left key name raises ValueError with the missing name interpolated.

Source

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

                    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"
                raise ValueError(msg)

        # no need to join if *only* join columns are in other (inner/left update only)
        if how != "full" and len(right_schema) == len(right_on):
            if row_index_name is not None:
                return self.drop(row_index_name)
            return self

        # only use non-idx right columns present in left frame
        right_other = set(right_schema).intersection(left_schema) - set(right_on)

        # When include_nulls is True, we need to distinguish records after the join that
        # were originally null in the right frame, as opposed to records that were null
        # because the key was missing from the right frame.

View on GitHub (pinned to df599052da)

Solutions

1. Inspect the schema with lf.collect_schema() and use the exact left-frame name in `on`/left_on
2. If key names differ, use left_on/right_on with each frame's own name
3. If upstream renamed the key, rename it back or update downstream references

Example fix

// before
lf.update(other, on='Id')  # left column is actually 'id'

// after
lf.update(other, left_on='id', right_on='Id')

left_keys = [on] if isinstance(on, str) else (on or left_on or [])
left_schema = lf.collect_schema()
missing = [c for c in left_keys if c not in left_schema]
if missing:
    raise KeyError(f'left keys not in schema: {missing}; have {list(left_schema)}')

When it happens

Trigger: lf.update(other, on='Id') when the left frame's column is 'id'; typos; upstream rename/select removed the key; using the RIGHT frame's key name in `on`/left_on when names differ.

Common situations: Schema drift in pipelines (a select/rename earlier in the chain changed names); case-mismatched keys ('Id' vs 'id'); keys that differ between frames.

Related errors

• right join column {name!r} not found
• `how` must be one of {'left', 'inner', 'full'}; found {how!r
• missing join columns for left frame
• missing join columns for right frame
• 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/58f142b2fe135670. Report an issue: GitHub.