pola-rs/polars · error

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

Error message

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

What it means

Polars Datetime/Duration time units are restricted to milliseconds ('ms'), microseconds ('us'), and nanoseconds ('ns'). _raise_invalid_time_unit is the single choke point that fires whenever a time_unit argument is anything else — including plausible-but-unsupported values like 's', 'm', 'h', or the Unicode 'µs'.

Source

Thrown at py-polars/src/polars/_utils/convert.py:224

        _raise_invalid_time_unit(time_unit)


def to_py_decimal(prec: int, value: str) -> Decimal:
    """Convert decimal components to a Python Decimal object."""
    return _create_decimal_with_prec(prec)(value)


@lru_cache(None)
def _create_decimal_with_prec(
    precision: int,
) -> Callable[[str], Decimal]:
    # pre-cache contexts so we don't have to spend time on recreating them every time
    return Context(prec=precision).create_decimal


def _raise_invalid_time_unit(time_unit: Any) -> NoReturn:
    msg = f"`time_unit` must be one of {{'ms', 'us', 'ns'}}, got {time_unit!r}"
    raise ValueError(msg)

View on GitHub (pinned to df599052da)

Solutions

1. Use exactly one of 'ms', 'us', 'ns'.
2. For epoch seconds/minutes use pl.from_epoch(s, time_unit="s") instead of a Datetime time_unit.
3. Check for Unicode mu vs ASCII 'u' when the literal was copied from rendered docs.
4. Validate the unit against {'ms','us','ns'} before calling APIs that take time_unit.

Example fix

// before
s = pl.Series("ts", [1700000000], dtype=pl.Int64).cast(pl.Datetime("s"))

// after
s = pl.from_epoch(pl.Series("ts", [1700000000]), time_unit="s")  # Datetime('us')

if time_unit not in {"ms", "us", "ns"}:
    raise ValueError(f"time_unit must be 'ms', 'us', or 'ns', got {time_unit!r}")
dtype = pl.Datetime(time_unit)

def is_valid_time_unit(time_unit: object) -> bool:
    return time_unit in ("ms", "us", "ns")

When it happens

Trigger: pl.Series(values, dtype=pl.Datetime("s")); pl.Duration("m"); s.cast(pl.Datetime("us")) mistyped as "μs" (Greek mu) or "US"; epoch-seconds data passed with time_unit="s".

Common situations: Converting epoch-seconds data (the unit does not exist — use pl.from_epoch); copy-pasting 'µs' from documentation renderings; vocab confusion with pandas/NumPy units like 'h' or 'D'.

Related errors

• `time_unit` must be one of {'ns', 'us', 'ms', 's', 'd'}, got
• comparing datetimes with different units or timezones is not
• `orient` must be one of {'col', 'row', None}, got {orient!r}
• 'float' object cannot be interpreted as a {python_dtype.__na
• unexpected time zone offset: {offset!r}

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