{"record":{"id":"ff15c0c5cd77a7de","repo":"pola-rs/polars","slug":"cannot-use-on-in-conjunction-with-left-on-or","errorCode":null,"errorMessage":"cannot use 'on' in conjunction with 'left_on' or 'right_on'","messagePattern":"cannot use 'on' in conjunction with 'left_on' or 'right_on'","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/lazyframe/frame.py","lineNumber":6226,"sourceCode":"        │ 2   ┆ 7.0 ┆ b   ┆ y     ┆ b         │\n        │ 2   ┆ 7.0 ┆ b   ┆ z     ┆ d         │\n        │ 3   ┆ 8.0 ┆ c   ┆ x     ┆ a         │\n        │ 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                    [],","sourceCodeStart":6208,"sourceCodeEnd":6244,"githubUrl":"https://github.com/pola-rs/polars/blob/fe841f959ef4d2ceefc05a310d33ed7b1ab24e5e/py-polars/src/polars/lazyframe/frame.py#L6208-L6244","documentation":"LazyFrame.join() does not allow `on` together with `left_on`/`right_on` — they are two alternative ways to specify join keys, and using both is ambiguous. The library raises ValueError early to prevent silently inconsistent key specifications.","triggerScenarios":"Calling lf.join(other, on='id', left_on='lkey') or lf.join(other, on='id', right_on='rkey'); any call where on is not None AND at least one of left_on/right_on is not None.","commonSituations":"Refactoring a join from same-name keys to different-name keys and leaving the old `on=` in place; IDE autocomplete filling both parameters; copy-paste between join variants.","solutions":["Remove `on` and keep only left_on/right_on when key names differ between frames","Remove left_on/right_on and keep only `on` when the key column has the same name in both frames"],"exampleFix":"// before\ndf.join(other, on='id', left_on='left_id', right_on='right_id')\n// after\ndf.join(other, left_on='left_id', right_on='right_id')","handlingStrategy":"validation","validationCode":"def check_join_args(on, left_on, right_on):\n    if on is not None and (left_on is not None or right_on is not None):\n        raise ValueError('use on= OR left_on/right_on, not both')","typeGuard":"def keys_are_exclusive(on, left_on, right_on) -> bool:\n    return not (on is not None and (left_on is not None or right_on is not None))","tryCatchPattern":"try:\n    out = df.join(other, on=key)\nexcept ValueError as e:\n    if \"in conjunction with 'left_on'\" in str(e):\n        out = df.join(other, left_on=lk, right_on=rk)\n    else:\n        raise","preventionTips":["Pick one key specification style per call site","When refactoring on= to left_on/right_on, delete the on= argument","Centralize join logic in one helper that enforces exclusivity"],"tags":["polars","python","join","conflicting-arguments"],"backgroundTag":"mutually-exclusive-options","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"}