pathwaycom/pathway · error · ValueError

The id argument of a join has to be a ColumnReference.

Error message

The id argument of a join has to be a ColumnReference.

What it means

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.

Source

Thrown at python/pathway/internals/arg_handlers.py:115

        if "id" in kwargs:
            id = kwargs.pop("id")
            processed_kwargs["id"] = id
            if not allow_id:
                raise ValueError(
                    "Received `id` argument but was not expecting any.\n"
                    + "Not every join type supports `id` argument."
                )
            elif id is None:
                pass
            elif isinstance(id, str):
                raise ValueError(
                    "Received `id` argument of join that is a string.\n"
                    + f"Did you mean <table>.{id}"
                    + f" instead of {repr(id)}?"
                )
            elif not isinstance(id, expr.ColumnReference):
                raise ValueError(
                    "The id argument of a join has to be a ColumnReference."
                )

        if "defaults" in kwargs:
            processed_kwargs["defaults"] = kwargs.pop("defaults")

        if "left_instance" in kwargs and "right_instance" in kwargs:
            processed_kwargs["left_instance"] = kwargs.pop("left_instance")
            processed_kwargs["right_instance"] = kwargs.pop("right_instance")
        elif "left_instance" in kwargs or "right_instance" in kwargs:
            raise ValueError(
                "`left_instance` and `right_instance` arguments to join "
                + "should always be provided simultaneously"
            )

        if "direction" in kwargs:
            direction = processed_kwargs["direction"] = kwargs.pop("direction")
            from pathway.stdlib.temporal import Direction

View on GitHub (pinned to fa2f74a464)

Solutions

1. Provide both: left_instance=t1.instance, right_instance=t2.instance.
2. Check for typos in the kwarg names when building them dynamically.
3. Drop both if the join is not instance-scoped.

Example fix

# before
t1.join_inner(t2, t1.k == t2.k, left_instance=t1.instance)

# after
t1.join_inner(
    t2, t1.k == t2.k,
    left_instance=t1.instance,
    right_instance=t2.instance,
)

def checked_instance_kwargs(left_instance=None, right_instance=None):
    if (left_instance is None) != (right_instance is None):
        raise ValueError("left_instance and right_instance must be given together")
    kwargs = {}
    if left_instance is not None:
        kwargs = {"left_instance": left_instance, "right_instance": right_instance}
    return kwargs

t1.join_inner(t2, t1.k == t2.k, **checked_instance_kwargs(t1.instance, t2.instance))

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Received `how` argument but was not expecting any. Consider
• Received `id` argument but was not expecting any. Not every
• Received `how` argument of join that is a string. You probab
• How argument of join should be one of JoinMode.INNER, JoinMo
• Received `id` argument of join that is a string. Did you mea

AI-assisted analysis of pathwaycom/pathway@fa2f74a464 (2026-08-15). Data as JSON: /api/errors/2514c7e8728d3fd0. Report an issue: GitHub.