{"record":{"id":"aa36a9fc0121c083","repo":"pola-rs/polars","slug":"cross-join-should-not-pass-join-keys","errorCode":null,"errorMessage":"cross join should not pass join keys","messagePattern":"cross join should not pass join keys","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/lazyframe/frame.py","lineNumber":6236,"sourceCode":"            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,\n                    nulls_equal,\n                    how,\n                    suffix,\n                    validate,\n                    maintain_order,\n                    build_side=build_side,\n                    coalesce=None,","sourceCodeStart":6218,"sourceCodeEnd":6254,"githubUrl":"https://github.com/pola-rs/polars/blob/fe841f959ef4d2ceefc05a310d33ed7b1ab24e5e/py-polars/src/polars/lazyframe/frame.py#L6218-L6254","documentation":"A cross join (how='cross') produces the Cartesian product of both frames and by definition takes no join keys. Passing `on`, `left_on`, or `right_on` to a cross join is contradictory, so a ValueError is raised.","triggerScenarios":"Calling lf.join(other, how='cross', on='id') or with left_on/right_on set; typically from templated join code that always passes key columns regardless of strategy.","commonSituations":"Parameterized join helpers where `how` is dynamic but keys are hardcoded; intending a regular join but mistakenly setting how='cross'; refactoring an inner/outer join into a cross join without removing keys.","solutions":["Remove the on/left_on/right_on arguments when using how='cross'","If you actually need keyed matching, change `how` to 'inner', 'left', or 'full' and keep the keys","Filter the cross result with a predicate expression if you need conditional matching"],"exampleFix":"// before\ndf.join(other, on='id', how='cross')\n// after\ndf.join(other, how='cross')","handlingStrategy":"validation","validationCode":"def check_cross_keys(how, on, left_on, right_on):\n    if how == 'cross' and any(k is not None for k in (on, left_on, right_on)):\n        raise ValueError('cross join takes no join keys')","typeGuard":"def join_args_consistent(how, on, left_on, right_on) -> bool:\n    return how != 'cross' or (on is None and left_on is None and right_on is None)","tryCatchPattern":"try:\n    out = df.join(other, how=how, **keys_kw)\nexcept ValueError as e:\n    if 'cross join should not pass join keys' in str(e):\n        keys_kw = {}\n        out = df.join(other, how='cross')\n    else:\n        raise","preventionTips":["Only pass key arguments for non-cross strategies","In dynamic join helpers, build kwargs conditionally on `how`","Add a test for each join strategy in helper functions"],"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"}