pathwaycom/pathway · error · ValueError

Received `how` argument of join that is a string. You probab

Error message

Received `how` argument of join that is a string.
You probably want to use one of JoinMode.INNER, JoinMode.LEFT, JoinMode.RIGHT or JoinMode.OUTER values.

What it means

Where a join does accept 'how', Pathway requires a JoinMode enum member (pw.JoinMode.INNER/LEFT/RIGHT/OUTER) rather than a bare string like 'left'. Strings are error-prone (case, typos, aliases), so the shared join kwargs handler raises this ValueError when it sees isinstance(how, str) and lists the accepted enum values.

Source

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

    }


def join_kwargs_handler(*, allow_how: bool, allow_id: bool):
    def handler(self, other, *on, **kwargs):
        processed_kwargs = {}
        if "how" in kwargs:
            how = kwargs.pop("how")
            processed_kwargs["how"] = how
            if not allow_how:
                raise ValueError(
                    "Received `how` argument but was not expecting any.\n"
                    + "Consider using a generic join method that handles `how` "
                    + "to decide on a type of a join to be used."
                )
            elif isinstance(how, JoinMode):
                pass
            elif isinstance(how, str):
                raise ValueError(
                    "Received `how` argument of join that is a string.\n"
                    + "You probably want to use one of "
                    + "JoinMode.INNER, JoinMode.LEFT, JoinMode.RIGHT or JoinMode.OUTER values."
                )
            else:
                raise ValueError(
                    "How argument of join should be one of "
                    + "JoinMode.INNER, JoinMode.LEFT, JoinMode.RIGHT or JoinMode.OUTER values."
                )

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

View on GitHub (pinned to fa2f74a464)

Solutions

1. Use the enum: how=pw.JoinMode.LEFT (INNER, LEFT, RIGHT, OUTER).
2. Map config strings once at load: {'inner': pw.JoinMode.INNER, ...}[cfg['join_type']].
3. Or use the dedicated methods join_inner/join_left/join_right/join_outer which need no how at all.

Example fix

# before
t1.join(t2, t1.k == t2.k, how="left")

# after
t1.join(t2, t1.k == t2.k, how=pw.JoinMode.LEFT)

import pathway as pw

mode_str = cfg["join_type"]
mode_map = {
    "inner": pw.JoinMode.INNER,
    "left": pw.JoinMode.LEFT,
    "right": pw.JoinMode.RIGHT,
    "outer": pw.JoinMode.OUTER,
}
try:
    how = mode_map[mode_str.lower()]
except KeyError:
    raise ValueError(f"unknown join mode {mode_str!r}; expected one of {list(mode_map)}")

import pathway as pw

def is_join_mode(v) -> bool:
    return isinstance(v, pw.JoinMode)

When it happens

Trigger: t1.join(t2, t1.k == t2.k, how='left'); how='inner'; how read from a config string and passed through unconverted.

Common situations: pandas/Spark/SQL habits where how is a string; join type supplied via CLI flag or YAML config; older Pathway examples or tutorials that used string modes.

Related errors

• How argument of join should be one of JoinMode.INNER, JoinMo
• `left_instance` and `right_instance` arguments to join shoul
• Received `how` argument but was not expecting any. Consider
• Received `id` argument but was not expecting any. Not every
• 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/6caaf8de218c5d59. Report an issue: GitHub.