pathwaycom/pathway · error · ValueError

direction argument of join should be of type asof_join.Direc

Error message

direction argument of join should be of type asof_join.Direction.

What it means

Pathway's Table.join() argument preprocessor validates the `direction` kwarg used by as-of joins. `direction` must be a `pathway.stdlib.temporal.Direction` enum member (BACKWARD, FORWARD, NEAREST); strings or other objects are rejected before the join is built. Note the error text mentioning `asof_join.Direction` refers to the enum now exposed as `pw.temporal.Direction`.

Source

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

            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."
                )

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

            if not isinstance(behavior, CommonBehavior):
                raise ValueError(
                    "The behavior argument of join should be of type pathway.temporal.CommonBehavior."
                )

        if "interval" in kwargs:
            from pathway.stdlib.temporal import Interval

            interval = processed_kwargs["interval"] = kwargs.pop("interval")
            if not isinstance(interval, Interval):
                raise ValueError(

View on GitHub (pinned to fa2f74a464)

Solutions

Import and use the enum: from pathway.stdlib.temporal import Direction, then pass direction=Direction.BACKWARD (or FORWARD/NEAREST).
If you passed a string like direction="backward", replace it with the enum member.
If you typed direction=Direction (the class), use a member: Direction.BACKWARD.

Example fix

# before
t.join_asof(right, left_time, right_time, direction="BACKWARD")

# after
from pathway.stdlib.temporal import Direction
t.join_asof(right, left_time, right_time, direction=Direction.BACKWARD)

Defensive patterns

Strategy: type-guard

Validate before calling

from pathway.stdlib.temporal import Direction
assert isinstance(direction, Direction) and isinstance(direction, Direction), 'direction must be Direction.BACKWARD/FORWARD/NEAREST'

Type guard

from pathway.stdlib.temporal import Direction

def is_valid_direction(d) -> bool:
    return isinstance(d, Direction)

Prevention

Always construct direction from the Direction enum, never from strings.
Centralize temporal-join kwargs in one helper so direction is validated once.

When it happens

Trigger: Calling pw.Table.join(..., direction=...) or Table.join_asof with direction="BACKWARD" (a string), direction=True, or any non-Direction object. Passing the enum class itself (Direction) instead of a member (Direction.BACKWARD) also triggers it.

Common situations: Developers migrating from SQL-style APIs where direction is a string, or copy-pasting 'backward'/'forward' from docs examples; using asof_join with `mode`/`direction` parameters and assuming string literals like in pandas merge_asof.

Related errors

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