pola-rs/polars · error · ValueError

right join column not found

Error message

right join column {name!r} not found

What it means

Pre-flight join-key check in LazyFrame.join (left/right join paths): right_on columns are validated against the right frame's collected schema; a key name that is not a column of the other frame raises before execution, catching typos early.

Solutions

1. Verify with `other.collect_schema().names()` and correct the right_on name.
2. Rename or add the key column on `other` before joining.
3. Confirm the right frame is the intended one.

Example fix

// before
lf.join(other, left_on="lid", right_on="rid")  # other lacks 'rid'
// after
other = other.rename({"r_id": "rid"})
lf.join(other, left_on="lid", right_on="rid")

right_schema = other.collect_schema()
missing = [c for c in right_on if c not in right_schema]
if missing:
    raise ValueError(f"right frame missing join columns: {missing}")

try:
    out = lf.join(other, left_on=left_on, right_on=right_on, how=how)
except ValueError as e:
    if "right join column" in str(e):
        raise KeyError(f"right frame columns: {other.collect_schema().names()}") from e
    raise

When it happens

Trigger: Calling `lf.join(other, right_on="rid", ...)` where `other` lacks a column 'rid' — the loop over right_schema raises on the first missing name.

Common situations: Right frame loaded from a different source with changed column names; forgot to select/rename the key column on `other`; swapped arguments.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• left join column not found
• cannot use 'on' in conjunction with 'left_on' or 'right_on'
• cross join should not pass join keys
• dtypes must be fully-specified, got
• `how` must be one of

AI-assisted analysis of pola-rs/polars@fe841f959e (2026-09-18). Data as JSON: /api/errors/f8032833b189842d. Report an issue: GitHub.

Appendix: source

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

        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.
        # Add a validity column to track whether row was matched or not.
        if include_nulls:
            validity = ("__POLARS_VALIDITY",)
            other = other.with_columns(F.lit(True).alias(validity[0]))
        else:

View on GitHub (pinned to fe841f959e)