pola-rs/polars · error · ValueError

expected Series in 'arg_where' if 'eager=True', got {type(co

Error message

expected Series in 'arg_where' if 'eager=True', got {type(condition).__name__!r}

What it means

Raised by polars.arg_when... polars.arg_where when eager=True but the condition is not a pl.Series (usually it is an Expr or a column name). The eager path immediately evaluates by converting the condition to a one-column DataFrame and selecting arg_where on it, which only works on materialized Series data.

Source

Thrown at py-polars/src/polars/functions/lazy.py:2468

    >>> df.select(
    ...     [
    ...         pl.arg_where(pl.col("a") % 2 == 0),
    ...     ]
    ... ).to_series()
    shape: (2,)
    Series: 'a' [u32]
    [
        1
        3
    ]
    """
    if eager:
        if not isinstance(condition, pl.Series):
            msg = (
                "expected Series in 'arg_where' if 'eager=True', got"
                f" {type(condition).__name__!r}"
            )
            raise ValueError(msg)
        return condition.to_frame().select(arg_where(F.col(condition.name))).to_series()
    else:
        condition_pyexpr = parse_into_expression(condition)
        return wrap_expr(plr.arg_where(condition_pyexpr))


@overload
def coalesce(
    exprs: IntoExpr | Iterable[IntoExpr],
    *more_exprs: IntoExpr,
    eager: Literal[False] = ...,
) -> Expr: ...


@overload
def coalesce(
    exprs: IntoExpr | Iterable[IntoExpr],
    *more_exprs: IntoExpr,

View on GitHub (pinned to df599052da)

Solutions

1. Pass a Series condition: pl.arg_where(df['a'] > 1, eager=True)
2. Drop eager and use the expression inside a context: df.select(pl.arg_where(pl.col('a') > 1))
3. If you already hold a boolean mask, use mask.arg_true() or df.filter(mask) instead

Example fix

// before
pl.arg_where(pl.col('a') > 1, eager=True)
// after
pl.arg_where(df['a'] > 1, eager=True)
# or keep it lazy:
df.select(pl.arg_where(pl.col('a') > 1))

import polars as pl

if eager and not isinstance(condition, pl.Series):
    condition = df[condition.meta.output_name()] if isinstance(condition, pl.Expr) else df[condition]

def is_polars_series(x) -> bool:
    return isinstance(x, pl.Series)

try:
    out = pl.arg_where(condition, eager=True)
except ValueError:
    out = df.select(pl.arg_where(condition))  # fall back to lazy evaluation

When it happens

Trigger: Calling pl.arg_where(pl.col('a') > 1, eager=True); passing a string column name like pl.arg_where('a', eager=True); passing any non-Series object while eager=True.

Common situations: Copy-pasting a lazy expression into an eager context; refactoring df.select(pl.arg_where(...)) into a direct call; confusing arg_where with Series.arg_true or DataFrame.filter.

Related errors

• expected `by_predicate` to be an expression, got {qualified_
• expected at least one Series in 'coalesce' if 'eager=True'
• `n` parameter of `repeat expected a `int` or `Expr` got a `{
• cannot turn {qualified_type_name(input)!r} into selector
• Cannot pass a dictionary as a single positional argument.\nI

AI-assisted analysis of pola-rs/polars@df599052da (2026-08-16). Data as JSON: /api/errors/cd4c6637dfa2ab7b. Report an issue: GitHub.