pola-rs/polars · error · ValueError

require `span` >= 1 (found {span!r})

Error message

require `span` >= 1 (found {span!r})

What it means

_prepare_alpha requires span >= 1 because span maps to alpha = 2/(span+1); a span below 1 would produce alpha > 1, an invalid smoothing factor. span=1 means no smoothing (alpha=1) and is the accepted lower bound.

Source

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

    half_life: float | int | None = None,
    alpha: float | int | None = None,
) -> float:
    """Normalise EWM decay specification in terms of smoothing factor 'alpha'."""
    if sum((param is not None) for param in (com, span, half_life, alpha)) > 1:
        msg = (
            "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

View on GitHub (pinned to df599052da)

Solutions

1. Pass span >= 1 (e.g. span=5).
2. If the value is a proportion, convert: alpha = 2/(span+1) — or just pass it as alpha if in (0,1].
3. Guard computed spans with max(span, 1) if sub-1 values are possible but nonsensical in your domain.

Example fix

# before
pl.col('x').ewm_mean(span=0.5)

# after
pl.col('x').ewm_mean(span=5)
# proportion? then
pl.col('x').ewm_mean(alpha=0.5)

if span is not None:
    assert span >= 1, f'span must be >= 1, got {span!r}'

When it happens

Trigger: pl.col('x').ewm_mean(span=0.5) or span=0; often from dividing by a window that can collapse, or from a percentage (0..1) mistakenly passed where a span was expected.

Common situations: Confusing span with fraction/alpha (e.g. passing 0.2 intending 20% weight); spans computed as ratios; data-driven spans like span = n_observations / total where the ratio can drop below 1.

Related errors

• parameters `com`, `span`, `half_life`, and `alpha` are mutua
• require `com` >= 0 (found {com!r})
• require `half_life` > 0 (found {half_life!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/e161ef8be1662c01. Report an issue: GitHub.