{"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":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/lazyframe/frame.py","lineNumber":6426,"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\":\n            how = \"full\"\n            issue_deprecation_warning(\n                \"use of `how='outer'` should be replaced with `how='full'`.\",\n                version=\"0.20.29\",\n            )\n        elif how == \"outer_coalesce\":  # type: ignore[comparison-overlap]\n            coalesce = True\n            how = \"full\"\n            issue_deprecation_warning(\n                \"use of `how='outer_coalesce'` should be replaced with `how='full', coalesce=True`.\",\n                version=\"0.20.29\",\n            )\n        elif how == \"cross\":","sourceCodeStart":6408,"sourceCodeEnd":6444,"githubUrl":"https://github.com/pola-rs/polars/blob/df599052daf96e7a9cc30a3b0c6bd25d6947e3c0/py-polars/src/polars/lazyframe/frame.py#L6408-L6444","documentation":"LazyFrame.join() raises ValueError when on= is combined with left_on= or right_on=. on= means 'the same key on both frames'; left_on/right_on exist precisely for differing keys, so specifying both is ambiguous.","triggerScenarios":"lf.join(other, on='id', left_on='id') (redundant specification); refactors that added left_on/right_on without removing an existing on=; option dicts that always set on plus per-side keys.","commonSituations":"Parameterized join wrappers where on has a default value that is not cleared; incremental edits to join calls.","solutions":["Use on='id' alone when key names are identical","Use left_on= and right_on= alone (both required) when names differ","In wrappers, use sentinel logic so exactly one of the two styles is passed: kwargs.pop('on', None) before setting left_on/right_on"],"exampleFix":"# before\nlf.join(other, on='id', left_on='id', right_on='user_id')\n\n# after\nlf.join(other, left_on='id', right_on='user_id')","handlingStrategy":"validation","validationCode":"if on is not None:\n    assert left_on is None and right_on is None, 'do not mix on= with left_on/right_on='\n    kwargs = {'on': on}\nelse:\n    kwargs = {'left_on': left_on, 'right_on': right_on}\nlf.join(other, **kwargs, how=how)","typeGuard":"def uses_exclusive_join_keys(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":null,"preventionTips":["Choose one key style per call site and stick to it","In wrappers, normalize inputs to a single (left_keys, right_keys) pair","Use on= None default so stale values don't linger"],"tags":["polars","lazyframe","join","conflicting-arguments"],"backgroundTag":null,"analyzedSha":"df599052daf96e7a9cc30a3b0c6bd25d6947e3c0","analyzedAt":"2026-08-16T12:10:03.978Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}