pola-rs/polars · error · ValueError

require 0 < `alpha` <= 1 (found {alpha!r})

Error message

require 0 < `alpha` <= 1 (found {alpha!r})

What it means

_prepare_alpha's final validation: an explicitly supplied alpha must satisfy 0 < alpha <= 1, since alpha is a smoothing weight (1 means no smoothing, values approaching 0 mean near-total smoothing, and 0 itself would zero out all updates). The check is inclusive of 1 but exclusive of 0, and reports the found value.

Source

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

    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. Clamp or fix alpha into (0, 1]: alpha = min(max(alpha, _EPS), 1.0).
2. Re-derive alpha from span/com if the direct value is unreliable.
3. Reject out-of-range alphas at input parsing with a clear domain error.

Example fix

# before
pl.col('x').ewm_mean(alpha=1.5)

# after
pl.col('x').ewm_mean(alpha=min(alpha, 1.0))

if alpha is not None:
    assert 0 < alpha <= 1, f'alpha out of range: {alpha!r}'

When it happens

Trigger: pl.col('x').ewm_mean(alpha=1.5), ewm_mean(alpha=0), or alpha derived from arithmetic that can leave the range (e.g. unnormalised weights).

Common situations: Computing alpha from ratios without clamping; porting formulas where alpha is defined as 1 - lambda and lambda went negative; UI sliders exposing 0..1 inclusive where 0 gets forwarded.

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})
• one of `com`, `span`, `half_life`, or `alpha` must be set

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