pola-rs/polars · error · ValueError

missing join columns for right frame

Error message

missing join columns for right frame

What it means

Mirror case of the left-frame key check: join raises ValueError when only one of left_on/right_on is supplied or the right frame's join columns cannot be resolved, leaving the right side without keys.

Solutions

1. Add the matching `right_on="rcol"` argument.
2. Or use `on="col"` when the key column name is identical in both frames.
3. Pair left_on/right_on in helper functions to enforce completeness.

Example fix

// before
lf.join(other, left_on="lid")
// after
lf.join(other, left_on="lid", right_on="rid")

if on is None and right_on is None and left_on is not None:
    right_on = left_on
out = lf.join(other, on=on, left_on=left_on, right_on=right_on, how=how)

try:
    out = lf.join(other, left_on=left_on, right_on=right_on, how=how)
except ValueError as e:
    if "missing join columns for right frame" in str(e):
        out = lf.join(other, left_on=left_on, right_on=left_on, how=how)
    else:
        raise

When it happens

Trigger: Calling `lf.join(other, left_on="lid")` with `on=None` and `right_on=None`.

Common situations: Key columns named differently between frames and only one side supplied; assuming right_on defaults to left_on.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• 'left_on' requires corresponding 'right_on'
• missing join columns for left frame
• must specify `on` OR `left_on` and `right_on`
• you should pass the column to join on as an argument
• cannot use 'on' in conjunction with 'left_on' or 'right_on'

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

Appendix: source

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

            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 fe841f959e)