pola-rs/polars · error · ValueError

`time_unit` must be one of {'ns', 'us', 'ms', 's', 'd'}, got

Error message

`time_unit` must be one of {'ns', 'us', 'ms', 's', 'd'}, got {time_unit!r}

What it means

ValueError raised by pl.from_epoch when time_unit is not one of the supported epoch resolutions: 'ns', 'us', 'ms', 's', or 'd'. The function needs a scale factor to convert the integer column into a Datetime, so unrecognized units (e.g. 'm' for minutes, 'us ' with whitespace, or None) are rejected.

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 68506541d2)

Solutions

1. Pick one of 'ns','us','ms','s','d'; for minutes multiply manually: (col * 60_000_000).cast(pl.Datetime('us'))
2. Validate/whitelist the unit before calling from_epoch
3. Check for typos/whitespace in dynamically built unit strings

Example fix

# before
pl.from_epoch(pl.col('ts'), time_unit='m')
# after
(pl.col('ts') * 60_000_000).cast(pl.Datetime('us'))

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

def is_valid_time_unit(u: object) -> bool:
    return u in {'ns', 'us', 'ms', 's', 'd'}

try:
    pl.from_epoch(col, time_unit=u)
except ValueError:
    u = 's'
    pl.from_epoch(col, time_unit=u)

When it happens

Trigger: pl.from_epoch(col, time_unit='m'), time_unit=None, or a unit string read from config/user input without validation.

Common situations: Assuming minute/month granularity exists; units sourced from external metadata or user form fields; copy-paste from from_epoch docs of other libraries.

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

• `format` must be one of {{'binary', 'json'}}, got {format!r}
• use of `how='outer_coalesce'` should be replaced with `how='
• list.to_struct() got a str instead of a list. hint: pass ['{
• schema_mode='overwrite' requires mode='overwrite'
• unsupported temporal data type: {dtype!r}

AI-assisted analysis of pola-rs/polars@68506541d2 (2026-08-28). Data as JSON: /api/errors/8e3421e2c1240f13. Report an issue: GitHub.