pola-rs/polars · error · ValueError

one of `com`, `span`, `half_life`, or `alpha` must be set

Error message

one of `com`, `span`, `half_life`, or `alpha` must be set

What it means

_prepare_alpha's fallback branch fires when none of com, span, half_life, alpha is provided — every parameter defaults to None in ewm_mean, so a bare call has no decay specification at all. Since alpha cannot be inferred, polars raises ValueError rather than silently picking a default smoothing.

Source

Thrown at py-polars/src/polars/expr/expr.py:12814

            msg = f"require `com` >= 0 (found {com!r})"
            raise ValueError(msg)
        alpha = 1.0 / (1.0 + com)

    elif span is not None:
        if span < 1.0:
            msg = f"require `span` >= 1 (found {span!r})"
            raise ValueError(msg)
        alpha = 2.0 / (span + 1.0)

    elif half_life is not None:
        if half_life <= 0.0:
            msg = f"require `half_life` > 0 (found {half_life!r})"
            raise ValueError(msg)
        alpha = 1.0 - math.exp(-math.log(2.0) / half_life)

    elif alpha is None:
        msg = "one of `com`, `span`, `half_life`, or `alpha` must be set"
        raise ValueError(msg)

    elif not (0 < alpha <= 1):
        msg = f"require 0 < `alpha` <= 1 (found {alpha!r})"
        raise ValueError(msg)

    return alpha


def _prepare_rolling_by_window_args(window_size: timedelta | str) -> str:
    if isinstance(window_size, timedelta):
        window_size = parse_as_duration_string(window_size)
    return window_size

View on GitHub (pinned to df599052da)

Solutions

1. Add exactly one decay parameter, e.g. ewm_mean(span=10).
2. If a sensible default is wanted in your codebase, define it in your wrapper and always pass it.
3. Check that config parsing actually populates one of the four keys.

Example fix

# before
pl.col('x').ewm_mean()

# after
pl.col('x').ewm_mean(span=10)

provided = [p for p in (com, span, half_life, alpha) if p is not None]
assert len(provided) == 1, f'need exactly one decay param, got {provided}'

When it happens

Trigger: pl.col('x').ewm_mean() with no arguments; or ewm_mean(com=None, ...) via a config dict where the decay key was never populated.

Common situations: Copy-pasted examples trimmed too aggressively; wrapper functions forwarding optional EWM params where none ended up set; refactors that moved the decay argument out and forgot to keep one.

Related errors

• parameters `com`, `span`, `half_life`, and `alpha` are mutua
• require `com` >= 0 (found {com!r})
• require `span` >= 1 (found {span!r})
• require `half_life` > 0 (found {half_life!r})
• require 0 < `alpha` <= 1 (found {alpha!r})

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