pola-rs/polars · error · ValueError

`how` must be one of

Error message

`how` must be one of {'left', 'inner', 'full'}; found {how!r}

What it means

Raised as a ValueError when the `how` argument of this join is not one of the allowed strategies 'left', 'inner', or 'full'. This is fail-fast validation of the join strategy string before any execution.

Solutions

1. Use one of: 'left', 'inner', 'full'.
2. Check the method's docstring — this API supports only this subset.
3. Use the dedicated `join`/`join_asof` methods for other strategies.

Example fix

// before
lf.join(other, on="id", how="leftouter")
// after
lf.join(other, on="id", how="left")

_VALID_HOW = {"left", "inner", "full"}
if how not in _VALID_HOW:
    raise ValueError(f"how must be one of {sorted(_VALID_HOW)}; got {how!r}")
out = lf.join(other, on="id", how=how)

try:
    out = lf.join(other, on=key, how=how)
except ValueError as e:
    if "`how` must be one of" in str(e):
        out = lf.join(other, on=key, how="inner")
    else:
        raise

When it happens

Trigger: Calling `lf.join(other, on="id", how="semi")` or any misspelled value like "inner_join", "OUTER", or "leftouter" on this API.

Common situations: Copying pandas merge `how` values; typos; assuming other polars join strategies ('semi', 'anti', 'cross') are accepted by this particular method.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• cannot use credential_provider when passing a DeltaTable…
• cannot use 'on' in conjunction with 'left_on' or 'right_on'
• cross join should not pass join keys
• `format` must be one of
• invalid input for `aggregate_function` argument

AI-assisted analysis of pola-rs/polars@fe841f959e (2026-09-18). Data as JSON: /api/errors/af5659d46e515b39. Report an issue: GitHub.

Appendix: source

Thrown at py-polars/src/polars/lazyframe/frame.py:9037

        │ --- ┆ ---  │
        │ i64 ┆ i64  │
        ╞═════╪══════╡
        │ 1   ┆ -99  │
        │ 2   ┆ 500  │
        │ 3   ┆ null │
        │ 4   ┆ 700  │
        │ 5   ┆ -66  │
        └─────┴──────┘
        """
        require_same_type(self, other)

        if how in {"outer", "outer_coalesce"}:  # type: ignore[comparison-overlap]
            msg = f"use of `how='{how}'` should be replaced with `how='full'`."
            raise ValueError(msg)

        if how not in ("left", "inner", "full"):
            msg = f"`how` must be one of {{'left', 'inner', 'full'}}; found {how!r}"
            raise ValueError(msg)

        row_index_name = None
        if on is None:
            if left_on is None and right_on is None:
                # no keys provided--use row index
                row_index_name = "__POLARS_ROW_INDEX"
                self = self.with_row_index(row_index_name)
                other = other.with_row_index(row_index_name)
                left_on = right_on = [row_index_name]
            else:
                # one of left or right is missing, raise error
                if left_on is None:
                    msg = "missing join columns for left frame"
                    raise ValueError(msg)
                if right_on is None:
                    msg = "missing join columns for right frame"
                    raise ValueError(msg)
        else:

View on GitHub (pinned to fe841f959e)