pola-rs/polars · error · ValueError

`time_unit` must be one of

Error message

`time_unit` must be one of {valid_units}, got {time_unit!r}

What it means

`pl.from_epoch(column, time_unit=...)` converts integer epoch timestamps; only 'ns', 'us', 'ms', 's', 'd' are accepted time units. Any other value falls through the unit checks and raises ValueError listing the valid units. Note that for 'ns'/'us'/'ms'/'s' multiplication scaling applies, and 'd' casts to a Date-like unit.

Solutions

1. Use one of 'ns', 'us', 'ms', 's', 'd' exactly
2. Map your unit: seconds→'s', microseconds→'us', milliseconds→'ms', nanoseconds→'ns', days→'d'
3. Check the source of `time_unit` for case or whitespace issues

Example fix

// before
pl.from_epoch(col, time_unit="seconds")
// after
pl.from_epoch(col, time_unit="s")

VALID_EPOCH_UNITS = {"ns", "us", "ms", "s", "d"}
if time_unit not in VALID_EPOCH_UNITS:
    raise ValueError(f"time_unit must be one of {sorted(VALID_EPOCH_UNITS)}")

def is_valid_time_unit(u): return isinstance(u, str) and u in {"ns", "us", "ms", "s", "d"}

When it happens

Trigger: `pl.from_epoch(col, time_unit="sec")`, `time_unit="seconds"`, `time_unit="µs"`, or any misspelled/unsupported unit string.

Common situations: Using pandas-style unit strings ('s' vs 'sec'); assuming lowercase/abbreviated variants are accepted; migrating code with nonstandard unit names.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• expected 'time' to be a Python time or Polars expression…
• incorrect NumPy datetime resolution 'D' (datetime only)…
• method must be one of
• `time_unit` must be one of
• time zone of dtype ( ) differs from time zone of value ( )

AI-assisted analysis of pola-rs/polars@fe841f959e (2026-09-18). Data as JSON: /api/errors/644995c06f804a16. Report an issue: GitHub.

Appendix: source

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

        column = F.col(column)
    elif not isinstance(column, (pl.Series, pl.Expr)):
        column = pl.Series(column)

    if time_unit == "d":
        return column.cast(Date)
    if time_unit in (scale := {"s": 1_000_000, "ms": 1_000}):
        if isinstance(column, pl.Expr):
            column = column * F.lit(scale[time_unit], dtype=Int64)
            return column.cast(Datetime("us"))
        if column.dtype.is_integer():
            column = column.cast(Int64)
        return (column * scale[time_unit]).cast(Datetime("us"))
    if time_unit in DTYPE_TEMPORAL_UNITS:
        return column.cast(Datetime(time_unit))  # type: ignore[arg-type]

    valid_units = "'ns', 'us', 'ms', 's', 'd'"
    msg = f"`time_unit` must be one of {valid_units}, got {time_unit!r}"
    raise ValueError(msg)


@removed_parameters(
    RenamedParameter(
        name="min_periods",
        new_name="min_samples",
        deprecated_in="1.21.0",
        removed_in="2.0",
    ),
)
def rolling_cov(
    a: str | Expr,
    b: str | Expr,
    *,
    window_size: int,
    min_samples: int | None = None,
    ddof: int = 1,
) -> Expr:

View on GitHub (pinned to fe841f959e)