pola-rs/polars · error · ValueError

require `half_life` > 0 (found {half_life!r})

Error message

require `half_life` > 0 (found {half_life!r})

What it means

_prepare_alpha requires half_life > 0 (strictly positive): half_life maps to alpha = 1 - exp(-ln2/half_life), and zero or negative half_life makes the formula undefined or degenerate. Unlike span, even the boundary value 0 is rejected.

Source

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

            "parameters `com`, `span`, `half_life`, and `alpha` are mutually exclusive"
        )
        raise ValueError(msg)
    if com is not None:
        if com < 0.0:
            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. Pass a strictly positive half_life, e.g. ewm_mean(half_life=2.0).
2. If 0 means 'no smoothing' in your config, translate it to alpha=1 or skip the EWM call.
3. Validate data-derived half_lives at the point of computation, not inside the query.

Example fix

# before
pl.col('x').ewm_mean(half_life=0)

# after
pl.col('x').ewm_mean(half_life=2.0)

if half_life is not None:
    assert half_life > 0, f'half_life must be > 0, got {half_life!r}'

When it happens

Trigger: pl.col('x').ewm_mean(half_life=0) or half_life=-3; also pandas-style ewm(halflife=...) ports where a zero default slipped through.

Common situations: half_life computed from data or time deltas that can be zero (e.g. elapsed time of zero); config defaults set to 0 meaning 'disabled' but forwarded anyway; unit confusion (half-life in days passed as 0 for 'same day').

Related errors

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

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