{"record":{"id":"bf558d9290c0a708","repo":"pola-rs/polars","slug":"time-unit-must-be-one-of-ms-us-ns-got","errorCode":null,"errorMessage":"`time_unit` must be one of {'ms', 'us', 'ns'}, got {time_unit!r}","messagePattern":"`time_unit` must be one of (.+?), got (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/_utils/convert.py","lineNumber":224,"sourceCode":"        _raise_invalid_time_unit(time_unit)\n\n\ndef to_py_decimal(prec: int, value: str) -> Decimal:\n    \"\"\"Convert decimal components to a Python Decimal object.\"\"\"\n    return _create_decimal_with_prec(prec)(value)\n\n\n@lru_cache(None)\ndef _create_decimal_with_prec(\n    precision: int,\n) -> Callable[[str], Decimal]:\n    # pre-cache contexts so we don't have to spend time on recreating them every time\n    return Context(prec=precision).create_decimal\n\n\ndef _raise_invalid_time_unit(time_unit: Any) -> NoReturn:\n    msg = f\"`time_unit` must be one of {{'ms', 'us', 'ns'}}, got {time_unit!r}\"\n    raise ValueError(msg)\n","sourceCodeStart":206,"sourceCodeEnd":225,"githubUrl":"https://github.com/pola-rs/polars/blob/df599052daf96e7a9cc30a3b0c6bd25d6947e3c0/py-polars/src/polars/_utils/convert.py#L206-L225","documentation":"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'.","triggerScenarios":"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\".","commonSituations":"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'.","solutions":["Use exactly one of 'ms', 'us', 'ns'.","For epoch seconds/minutes use pl.from_epoch(s, time_unit=\"s\") instead of a Datetime time_unit.","Check for Unicode mu vs ASCII 'u' when the literal was copied from rendered docs.","Validate the unit against {'ms','us','ns'} before calling APIs that take time_unit."],"exampleFix":"// before\ns = pl.Series(\"ts\", [1700000000], dtype=pl.Int64).cast(pl.Datetime(\"s\"))\n\n// after\ns = pl.from_epoch(pl.Series(\"ts\", [1700000000]), time_unit=\"s\")  # Datetime('us')","handlingStrategy":"validation","validationCode":"if time_unit not in {\"ms\", \"us\", \"ns\"}:\n    raise ValueError(f\"time_unit must be 'ms', 'us', or 'ns', got {time_unit!r}\")\ndtype = pl.Datetime(time_unit)","typeGuard":"def is_valid_time_unit(time_unit: object) -> bool:\n    return time_unit in (\"ms\", \"us\", \"ns\")","tryCatchPattern":null,"preventionTips":["Centralize time units in one constant: TIME_UNITS = {'ms', 'us', 'ns'}.","Use pl.from_epoch for epoch seconds instead of inventing time_unit='s'.","Beware the Unicode 'µs' when copying from rendered docs; always type 'us'."],"tags":["time-unit","datetime","invalid-argument"],"backgroundTag":null,"analyzedSha":"df599052daf96e7a9cc30a3b0c6bd25d6947e3c0","analyzedAt":"2026-08-16T12:10:03.978Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}