{"record":{"id":"68fb754765759ac1","repo":"pola-rs/polars","slug":"missing-join-columns-for-left-frame","errorCode":null,"errorMessage":"missing join columns for left frame","messagePattern":"missing join columns for left frame","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/lazyframe/frame.py","lineNumber":9051,"sourceCode":"            raise ValueError(msg)\n\n        if how not in (\"left\", \"inner\", \"full\"):\n            msg = f\"`how` must be one of {{'left', 'inner', 'full'}}; found {how!r}\"\n            raise ValueError(msg)\n\n        row_index_name = None\n        if on is None:\n            if left_on is None and right_on is None:\n                # no keys provided--use row index\n                row_index_name = \"__POLARS_ROW_INDEX\"\n                self = self.with_row_index(row_index_name)\n                other = other.with_row_index(row_index_name)\n                left_on = right_on = [row_index_name]\n            else:\n                # one of left or right is missing, raise error\n                if left_on is None:\n                    msg = \"missing join columns for left frame\"\n                    raise ValueError(msg)\n                if right_on is None:\n                    msg = \"missing join columns for right frame\"\n                    raise ValueError(msg)\n        else:\n            # move on into left/right_on to simplify logic\n            left_on = right_on = on\n\n        if isinstance(left_on, str):\n            left_on = [left_on]\n        if isinstance(right_on, str):\n            right_on = [right_on]\n\n        left_schema = self.collect_schema()\n        for name in left_on:\n            if name not in left_schema:\n                msg = f\"left join column {name!r} not found\"\n                raise ValueError(msg)\n        right_schema = other.collect_schema()","sourceCodeStart":9033,"sourceCodeEnd":9069,"githubUrl":"https://github.com/pola-rs/polars/blob/fe841f959ef4d2ceefc05a310d33ed7b1ab24e5e/py-polars/src/polars/lazyframe/frame.py#L9033-L9069","documentation":"When neither on nor left_on/right_on is given, join falls back to a row-index join and raises ValueError if it cannot establish the left frame's join columns (e.g. they were dropped or renamed), leaving the left side without keys.","triggerScenarios":"Calling `lf.join(other, right_on=\"rid\")` with `on=None` and `left_on=None` — the 'one of left or right is missing' branch raises.","commonSituations":"Forgetting `left_on` when key column names differ between frames; partially refactoring from `on=` to `left_on=`/`right_on=`.","solutions":["Add the matching `left_on=\"lcol\"` argument.","Or use `on=\"col\"` when both frames share the same key column name.","Always supply left_on and right_on together."],"exampleFix":"// before\nlf.join(other, right_on=\"rid\")\n// after\nlf.join(other, left_on=\"lid\", right_on=\"rid\")","handlingStrategy":"validation","validationCode":"if on is None and (left_on is None) != (right_on is None):\n    raise ValueError(\"provide both left_on and right_on, or use on\")\nout = lf.join(other, on=on, left_on=left_on, right_on=right_on, how=how)","typeGuard":null,"tryCatchPattern":"try:\n    out = lf.join(other, left_on=left_on, right_on=right_on, how=how)\nexcept ValueError as e:\n    if \"missing join columns\" in str(e):\n        out = lf.join(other, on=on, how=how)\n    else:\n        raise","preventionTips":["Prefer `on=` when key names match on both frames.","Pair left_on/right_on together in helper signatures.","Validate key-argument completeness before building joins dynamically."],"tags":["python","polars","join","missing-argument"],"backgroundTag":"missing-required-argument","analyzedSha":"fe841f959ef4d2ceefc05a310d33ed7b1ab24e5e","analyzedAt":"2026-09-18T22:14:11.667Z","contentChangedAt":"2026-09-18T22:14:11.667Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}