pola-rs/polars · error · ValueError

you should pass the column to join on as an argument

Error message

you should pass the column to join on as an argument

What it means

LazyFrame.join_asof() requires join key(s): either `on`, or both `left_on` and `right_on`. If none resolve to a column, this ValueError is raised because an asof join cannot match rows without a key column (typically the time column).

Solutions

  1. Pass on='column_name' to join on the same-named column in both frames
  2. Or pass both left_on='lcol' and right_on='rcol' for differently named key columns
  3. Ensure the key column exists and is sorted in both frames (required for asof semantics)

Example fix

// before
left.join_asof(right, by='ticker')
// after
left.join_asof(right, on='timestamp', by='ticker')
Defensive patterns

Strategy: validation

Validate before calling

def check_asof_args(on, left_on, right_on):
    if on is None and (left_on is None or right_on is None):
        raise ValueError('join_asof needs on= or both left_on= and right_on=')
    key = on if on is not None else left_on
    assert key in left.columns and key in right.columns

Type guard

def has_asof_keys(on, left_on, right_on) -> bool:
    return on is not None or (left_on is not None and right_on is not None)

Try / catch

try:
    out = left.join_asof(right, on='ts', by='ticker')
except ValueError as e:
    if 'join on as an argument' in str(e):
        raise KeyError('join_asof requires on= (e.g. on=\'timestamp\')') from e
    raise

Prevention

When it happens

Trigger: Calling lf.join_asof(other) with on=None and left_on/right_on both None (or only one of left_on/right_on given); note that when `on` is a plain string it also populates left_on/right_on, so omitting all three triggers the error.

Common situations: Copy-pasting a join_asof call and forgetting the `on='time'` argument; assuming the join matches on index like pandas merge without keys; passing `by` (the within-group columns) but forgetting the actual asof key.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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

Appendix: source

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

        │ str         ┆ date       ┆ f64        ┆ i64  │
        ╞═════════════╪════════════╪════════════╪══════╡
        │ Germany     ┆ 2016-03-01 ┆ 82.19      ┆ 4164 │
        │ Germany     ┆ 2018-08-01 ┆ 82.66      ┆ 4696 │
        │ Germany     ┆ 2019-01-01 ┆ 83.12      ┆ 4696 │
        │ Netherlands ┆ 2016-03-01 ┆ 17.11      ┆ 784  │
        │ Netherlands ┆ 2018-08-01 ┆ 17.32      ┆ 910  │
        │ Netherlands ┆ 2019-01-01 ┆ 17.4       ┆ 910  │
        └─────────────┴────────────┴────────────┴──────┘
        """
        require_same_type(self, other)

        if isinstance(on, (str, pl.Expr)):
            left_on = on
            right_on = on

        if left_on is None or right_on is None:
            msg = "you should pass the column to join on as an argument"
            raise ValueError(msg)

        if by is not None:
            by_left_ = [by] if isinstance(by, str) else by
            by_right_ = by_left_
        elif (by_left is not None) or (by_right is not None):
            by_left_ = [by_left] if isinstance(by_left, str) else by_left  # type: ignore[assignment]
            by_right_ = [by_right] if isinstance(by_right, str) else by_right  # type: ignore[assignment]

        else:
            # no by
            by_left_ = None
            by_right_ = None

        tolerance_str: str | None = None
        tolerance_num: float | int | None = None
        if isinstance(tolerance, str):
            tolerance_str = tolerance
        elif isinstance(tolerance, timedelta):

View on GitHub (pinned to fe841f959e)