{"record":{"id":"e1c7935426fe3e9c","repo":"pola-rs/polars","slug":"left-on-requires-corresponding-right-on","errorCode":null,"errorMessage":"'left_on' requires corresponding 'right_on'","messagePattern":"'left_on' requires corresponding 'right_on'","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/lazyframe/frame.py","lineNumber":6229,"sourceCode":"        │ 3   ┆ 8.0 ┆ c   ┆ y     ┆ b         │\n        │ 3   ┆ 8.0 ┆ c   ┆ z     ┆ d         │\n        └─────┴─────┴─────┴───────┴───────────┘\n        \"\"\"\n        require_same_type(self, other)\n\n        if maintain_order is None:\n            maintain_order = \"none\"\n\n        uses_on = on is not None\n        uses_left_on = left_on is not None\n        uses_right_on = right_on is not None\n        uses_lr_on = uses_left_on or uses_right_on\n        if uses_on and uses_lr_on:\n            msg = \"cannot use 'on' in conjunction with 'left_on' or 'right_on'\"\n            raise ValueError(msg)\n        elif uses_left_on != uses_right_on:\n            msg = \"'left_on' requires corresponding 'right_on'\"\n            raise ValueError(msg)\n\n        if how == \"outer\":  # type: ignore[comparison-overlap]\n            msg = \"use of `how='outer'` should be replaced with `how='full'`.\"\n            raise ValueError(msg)\n        elif how == \"outer_coalesce\":  # type: ignore[comparison-overlap]\n            msg = \"use of `how='outer_coalesce'` should be replaced with `how='full', coalesce=True`.\"\n            raise ValueError(msg)\n        elif how == \"cross\":\n            if uses_on or uses_lr_on:\n                msg = \"cross join should not pass join keys\"\n                raise ValueError(msg)\n            return self._from_pyldf(\n                self._ldf.join(\n                    other._ldf,\n                    [],\n                    [],\n                    allow_parallel,\n                    force_parallel,","sourceCodeStart":6211,"sourceCodeEnd":6247,"githubUrl":"https://github.com/pola-rs/polars/blob/fe841f959ef4d2ceefc05a310d33ed7b1ab24e5e/py-polars/src/polars/lazyframe/frame.py#L6211-L6247","documentation":"LazyFrame.join() requires `left_on` and `right_on` to be provided together: they pair each left key column with a corresponding right key column. Supplying only one leaves the pairing incomplete, so a ValueError is raised.","triggerScenarios":"Calling lf.join(other, left_on='lkey') without right_on, or lf.join(other, right_on='rkey') without left_on; also passing a list to one side and None to the other.","commonSituations":"Joining frames whose key columns have different names and forgetting the second parameter; partial edits when renaming join keys; misunderstanding that `on` cannot substitute for one of the pair.","solutions":["Provide both: lf.join(other, left_on='lkey', right_on='rkey')","If the key column name is identical in both frames, use `on='key'` instead","For multiple keys, pass equal-length lists to left_on and right_on"],"exampleFix":"// before\ndf.join(other, left_on='user_id')\n// after\ndf.join(other, left_on='user_id', right_on='uid')","handlingStrategy":"validation","validationCode":"def check_lr_pair(left_on, right_on):\n    if (left_on is None) != (right_on is None):\n        raise ValueError('left_on and right_on must be provided together')","typeGuard":"def lr_pair_complete(left_on, right_on) -> bool:\n    return (left_on is None) == (right_on is None)","tryCatchPattern":"try:\n    out = df.join(other, left_on=lk, right_on=rk)\nexcept ValueError as e:\n    if \"'left_on' requires corresponding 'right_on'\" in str(e):\n        raise KeyError(f'missing join key: left_on={lk!r} needs right_on=') from e\n    raise","preventionTips":["Always supply left_on and right_on as a pair","Use on= when the key column name matches on both sides","For multi-key joins, assert len(left_on) == len(right_on) first"],"tags":["polars","python","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"}