{"record":{"id":"2514c7e8728d3fd0","repo":"pathwaycom/pathway","slug":"the-id-argument-of-a-join-has-to-be-a-columnrefere","errorCode":null,"errorMessage":"The id argument of a join has to be a ColumnReference.","messagePattern":"The id argument of a join has to be a ColumnReference\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/pathway/internals/arg_handlers.py","lineNumber":115,"sourceCode":"\n        if \"id\" in kwargs:\n            id = kwargs.pop(\"id\")\n            processed_kwargs[\"id\"] = id\n            if not allow_id:\n                raise ValueError(\n                    \"Received `id` argument but was not expecting any.\\n\"\n                    + \"Not every join type supports `id` argument.\"\n                )\n            elif id is None:\n                pass\n            elif isinstance(id, str):\n                raise ValueError(\n                    \"Received `id` argument of join that is a string.\\n\"\n                    + f\"Did you mean <table>.{id}\"\n                    + f\" instead of {repr(id)}?\"\n                )\n            elif not isinstance(id, expr.ColumnReference):\n                raise ValueError(\n                    \"The id argument of a join has to be a ColumnReference.\"\n                )\n\n        if \"defaults\" in kwargs:\n            processed_kwargs[\"defaults\"] = kwargs.pop(\"defaults\")\n\n        if \"left_instance\" in kwargs and \"right_instance\" in kwargs:\n            processed_kwargs[\"left_instance\"] = kwargs.pop(\"left_instance\")\n            processed_kwargs[\"right_instance\"] = kwargs.pop(\"right_instance\")\n        elif \"left_instance\" in kwargs or \"right_instance\" in kwargs:\n            raise ValueError(\n                \"`left_instance` and `right_instance` arguments to join \"\n                + \"should always be provided simultaneously\"\n            )\n\n        if \"direction\" in kwargs:\n            direction = processed_kwargs[\"direction\"] = kwargs.pop(\"direction\")\n            from pathway.stdlib.temporal import Direction","sourceCodeStart":97,"sourceCodeEnd":133,"githubUrl":"https://github.com/pathwaycom/pathway/blob/fa2f74a4649b7c5908690cf60137263d8d80de5f/python/pathway/internals/arg_handlers.py#L97-L133","documentation":"Joins that support instance-based (per-instance) matching require 'left_instance' and 'right_instance' together: they pair the instance columns of the left and right tables. Supplying only one of them leaves the pairing undefined, so the shared join kwargs handler raises this ValueError when exactly one of the two kwargs is present.","triggerScenarios":"t1.join_inner(t2, t1.k == t2.k, left_instance=t1.i) without right_instance; the mirror case with only right_instance; constructing kwargs dynamically where one key's condition evaluated falsy.","commonSituations":"Per-session or per-tenant joins (iot/ sessions) where the right table's instance column has a different name and one line was forgotten; refactoring instance joins and dropping one kwarg; building kwargs dicts conditionally with a typo in one key.","solutions":["Provide both: left_instance=t1.instance, right_instance=t2.instance.","Check for typos in the kwarg names when building them dynamically.","Drop both if the join is not instance-scoped."],"exampleFix":"# before\nt1.join_inner(t2, t1.k == t2.k, left_instance=t1.instance)\n\n# after\nt1.join_inner(\n    t2, t1.k == t2.k,\n    left_instance=t1.instance,\n    right_instance=t2.instance,\n)","handlingStrategy":"validation","validationCode":"def checked_instance_kwargs(left_instance=None, right_instance=None):\n    if (left_instance is None) != (right_instance is None):\n        raise ValueError(\"left_instance and right_instance must be given together\")\n    kwargs = {}\n    if left_instance is not None:\n        kwargs = {\"left_instance\": left_instance, \"right_instance\": right_instance}\n    return kwargs\n\nt1.join_inner(t2, t1.k == t2.k, **checked_instance_kwargs(t1.instance, t2.instance))","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always pass left_instance and right_instance as a pair in one kwargs dict.","Double-check key spelling when building instance kwargs dynamically."],"tags":["join","instance","api-misuse","kwargs"],"backgroundTag":null,"analyzedSha":"fa2f74a4649b7c5908690cf60137263d8d80de5f","analyzedAt":"2026-08-15T01:48:17.006Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}