pola-rs/polars · error · ValueError

expected at least one Series in 'corr' inputs if 'eager=True

Error message

expected at least one Series in 'corr' inputs if 'eager=True'

What it means

pl.corr(..., eager=True) computes the correlation immediately by building a one-shot DataFrame from the Series inputs, so at least one of a/b must be a pl.Series to supply rows. Two Exprs or two bare column-name strings have no data context, and the ValueError fires before anything is evaluated.

Source

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

        0.544705
    ]
    >>> pl.corr(s1, s2, method="spearman", eager=True)
    shape: (1,)
    Series: 'a' [f64]
    [
        0.5
    ]
    """
    if ddof is not None:
        issue_deprecation_warning(
            "the `ddof` parameter has no effect. Do not use it.",
            version="1.17.0",
        )

    if eager:
        if not (isinstance(a, pl.Series) or isinstance(b, pl.Series)):
            msg = "expected at least one Series in 'corr' inputs if 'eager=True'"
            raise ValueError(msg)

        frame = pl.DataFrame([e for e in (a, b) if isinstance(e, pl.Series)])
        exprs = ((e.name if isinstance(e, pl.Series) else e) for e in (a, b))
        return frame.select(
            corr(*exprs, eager=False, method=method, propagate_nans=propagate_nans)
        ).to_series()
    else:
        a_pyexpr = parse_into_expression(a)
        b_pyexpr = parse_into_expression(b)

        if method == "pearson":
            return wrap_expr(plr.pearson_corr(a_pyexpr, b_pyexpr))
        elif method == "spearman":
            return wrap_expr(plr.spearman_rank_corr(a_pyexpr, b_pyexpr, propagate_nans))
        else:
            msg = f"method must be one of {{'pearson', 'spearman'}}, got {method!r}"
            raise ValueError(msg)

View on GitHub (pinned to df599052da)

Solutions

Pass Series: pl.corr(df['a'], df['b'], eager=True)
Or evaluate expressions in a context: df.select(pl.corr('a', 'b')).item()
Remember mixed Series + Expr works — the Expr is evaluated against the frame built from the Series

Example fix

# before
pl.corr('a', 'b', eager=True)  # ValueError

# after
pl.corr(df['a'], df['b'], eager=True)
# or
df.select(pl.corr('a', 'b')).item()

Defensive patterns

Strategy: validation

Validate before calling

if eager and not (isinstance(a, pl.Series) or isinstance(b, pl.Series)):
    result = df.select(pl.corr(a, b)).item()  # context-based fallback
else:
    result = pl.corr(a, b, eager=eager, method=method)

Type guard

def has_series_input(a, b) -> bool:
    return isinstance(a, pl.Series) or isinstance(b, pl.Series)

Prevention

Treat eager=True as 'I am handing you data', not 'resolve these column names now'
Prefer df.select(pl.corr(...)) inside pipelines

When it happens

Trigger: pl.corr('a', 'b', eager=True); pl.corr(pl.col('a'), pl.col('b'), eager=True) outside a select/context; renaming a working df.select(pl.corr(...)) call into a standalone eager call.

Common situations: Moving a correlation out of select() into a summary function and adding eager=True; porting example code that used Series; mixing names and expressions in quick scripts.

Related errors

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