pathwaycom/pathway · error · ValueError

`left_instance` and `right_instance` arguments to join shoul

Error message

`left_instance` and `right_instance` arguments to join should always be provided simultaneously

What it means

The 'direction' kwarg of asof-style joins must be a pathway.stdlib.temporal.Direction enum (BACKWARD, FORWARD, NEAREST), not a string. Passing direction='backward' triggers this ValueError in the shared join kwargs handler, which imports Direction locally and isinstance-checks the value; the string case gets its own message listing the valid enum members.

Source

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

            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

            if isinstance(direction, str):
                raise ValueError(
                    "Received `direction` argument of join that is a string.\n"
                    + "You probably want to use one of "
                    + "Direction.BACKWARD, Direction.FORWARD or Direction.NEAREST values."
                )
            if not isinstance(direction, Direction):
                raise ValueError(
                    "direction argument of join should be of type asof_join.Direction."
                )

View on GitHub (pinned to fa2f74a464)

Solutions

Use the enum: direction=pw.stdlib.temporal.Direction.BACKWARD (or FORWARD/NEAREST).
Map config strings once: {'backward': Direction.BACKWARD, ...}[cfg['direction']].
Remember BACKWARD is the default for asof joins if you can omit the argument.

Example fix

# before
pw.io.asof_join(left, right, left.time == right.time, direction="backward")

# after
from pathway.stdlib.temporal import Direction
pw.io.asof_join(left, right, left.time == right.time, direction=Direction.BACKWARD)

Defensive patterns

Strategy: type-guard

Validate before calling

from pathway.stdlib.temporal import Direction

direction = {
    "backward": Direction.BACKWARD,
    "forward": Direction.FORWARD,
    "nearest": Direction.NEAREST,
}[cfg["asof_direction"].lower()]

Type guard

from pathway.stdlib.temporal import Direction

def is_direction(v) -> bool:
    return isinstance(v, Direction)

Prevention

Use Direction.BACKWARD/FORWARD/NEAREST instead of strings.
Map config strings to Direction members once at load time.
BACKWARD is the default for asof joins — omit direction when that is what you want.

When it happens

Trigger: io.asof_join(left, right, ..., direction='backward'); direction read from config as a string; porting pandas merge_asof(direction='backward') calls unchanged.

Common situations: pandas merge_asof habits; join direction supplied by CLI/config; older snippets predating the enum requirement.

Related errors

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