pathwaycom/pathway · error · ValueError

Join received extra kwargs. You probably want to use TableLi

Error message

Join received extra kwargs.
You probably want to use TableLike.join(...).select(**kwargs) to compute output columns.

What it means

Pathway's join argument handler rejects any leftover keyword arguments after known kwargs (how, id, direction, behavior, interval, left_exactly_once, right_exactly_once, mode, etc.) are consumed. This guards against the common mistake of trying to define output columns inside join(), which in Pathway is done by chaining .select(**kwargs) on the join result.

Source

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

                )

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

            interval = processed_kwargs["interval"] = kwargs.pop("interval")
            if not isinstance(interval, Interval):
                raise ValueError(
                    "The interval argument of a join should be of a type pathway.temporal.Interval."
                )

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

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

        if kwargs:
            raise ValueError(
                "Join received extra kwargs.\n"
                + "You probably want to use TableLike.join(...).select(**kwargs) to compute output columns."
            )
        return (self, other, *on), processed_kwargs

    return handler


def reduce_args_handler(self, *args, **kwargs):
    for arg in args:
        if expr.smart_name(arg) is None:
            if isinstance(arg, str):
                raise ValueError(
                    f"Expected a ColumnReference, found a string. Did you mean this.{arg} instead of {repr(arg)}?"
                )
            else:
                raise ValueError(
                    "In reduce() all positional arguments have to be a ColumnReference."

View on GitHub (pinned to fa2f74a464)

Solutions

Move output-column definitions to a chained select: table_a.join(table_b, on).select(new_col=table_a.value + table_b.value).
Check the exact join signature for your Pathway version (Table.join vs Table.join_left/join_outer vs join_asof) and use the method that accepts the kwargs you pass.
Ensure you are not passing a kwarg meant for join_asof (direction/behavior/interval) to plain join.

Example fix

# before
result = t1.join(t2, t1.id == t2.id, total=t1.price + t2.price)

# after
result = t1.join(t2, t1.id == t2.id).select(total=t1.price + t2.price)

Defensive patterns

Strategy: validation

Validate before calling

allowed = {'how', 'id', 'mode', 'direction', 'behavior', 'interval', 'left_exactly_once', 'right_exactly_once'}
extra = set(kwargs) - allowed
assert not extra, f'join() got unsupported kwargs {extra}; put output columns in .select()'

Prevention

Treat join() as join-only; always chain .select(**kwargs) for output columns.
Pin the join kwargs your Pathway version supports in a thin wrapper function.

When it happens

Trigger: Calling table_a.join(table_b, table_a.key == table_b.key, my_col=table_a.value + 1) — the my_col kwarg is not a join parameter so it survives popping and triggers the error.

Common situations: Developers coming from pandas merge/sql or Spark where join takes column expressions; writing join(..., left_time=..., right_time=...) on a plain (non-temporal) join in a version that does not accept those kwargs.

Related errors

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