{"record":{"id":"e10dfcdf32ad8c50","repo":"pola-rs/polars","slug":"invalid-time-unit-n-nexpected-one-of-ns-us-ms-got-time-unit","errorCode":null,"errorMessage":"invalid `time_unit`\\n\\nExpected one of {'ns','us','ms'}, got {time_unit!r}.","messagePattern":"invalid `time_unit`\\\\n\\\\nExpected one of (.+?), got (.+?)\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/datatypes/classes.py","lineNumber":608,"sourceCode":"    -----\n    The underlying representation of this type is a 64-bit signed integer.\n    The integer indicates the number of time units since the Unix epoch\n    (1970-01-01 00:00:00). The number can be negative to indicate datetimes before the\n    epoch.\n    \"\"\"\n\n    time_unit: TimeUnit\n    time_zone: str | None\n\n    def __init__(\n        self, time_unit: TimeUnit = \"us\", time_zone: str | tzinfo | None = None\n    ) -> None:\n        if time_unit not in (\"ms\", \"us\", \"ns\"):\n            msg = (\n                \"invalid `time_unit`\"\n                f\"\\n\\nExpected one of {{'ns','us','ms'}}, got {time_unit!r}.\"\n            )\n            raise ValueError(msg)\n\n        if isinstance(time_zone, tzinfo):\n            time_zone = str(time_zone)\n\n        self.time_unit = time_unit\n        self.time_zone = time_zone\n\n    def __eq__(self, other: PolarsDataType) -> bool:  # type: ignore[override]\n        # allow comparing object instances to class\n        if type(other) is DataTypeClass and issubclass(other, Datetime):\n            return True\n        elif isinstance(other, Datetime):\n            return (\n                self.time_unit == other.time_unit and self.time_zone == other.time_zone\n            )\n        else:\n            return False\n","sourceCodeStart":590,"sourceCodeEnd":626,"githubUrl":"https://github.com/pola-rs/polars/blob/fe841f959ef4d2ceefc05a310d33ed7b1ab24e5e/py-polars/src/polars/datatypes/classes.py#L590-L626","documentation":"Raised by the Datetime constructor's entry-point guard: the time_unit argument is not one of the resolutions polars can physically store. Datetimes are represented as 64-bit integers counting ticks since the Unix epoch, and only 'ns', 'us', and 'ms' tick sizes are supported; any other string (or non-string value) fails this membership check before the type is built.","triggerScenarios":"`pl.Datetime('s')`, `pl.Datetime('seconds')`, `pl.Datetime('')`, `pl.Datetime(None)` or any string other than 'ms', 'us', 'ns'.","commonSituations":"Developers expect seconds ('s') to be supported (as in pandas/DuckDB), or pass a time unit read from config in the wrong case ('US', 'NS').","solutions":["Use one of 'ms', 'us', 'ns' (default 'us')","Normalize/validate config-supplied time units before constructing `pl.Datetime`","Lowercase the input: `pl.Datetime(time_unit.lower())` if it may be uppercase"],"exampleFix":"// before\npl.Datetime('s')\n// after\npl.Datetime('us')","handlingStrategy":"validation","validationCode":"TIME_UNITS = {'ms', 'us', 'ns'}\nif time_unit not in TIME_UNITS:\n    raise ValueError(f'time_unit must be one of {TIME_UNITS}, got {time_unit!r}')","typeGuard":"from typing import Literal, TypeGuard\ndef is_valid_time_unit(u: object) -> TypeGuard[Literal['ms','us','ns']]:\n    return u in ('ms', 'us', 'ns')","tryCatchPattern":"try:\n    dt = pl.Datetime(time_unit)\nexcept ValueError as e:\n    if 'invalid `time_unit`' in str(e):\n        dt = pl.Datetime('us')\n    else:\n        raise","preventionTips":["Restrict time units to 'ms'/'us'/'ns' in configs","Lowercase and normalize unit strings before constructing Datetime"],"tags":["polars","datetime","validation","invalid-value"],"backgroundTag":"invalid-enum-value","analyzedSha":"fe841f959ef4d2ceefc05a310d33ed7b1ab24e5e","analyzedAt":"2026-09-18T22:14:11.667Z","contentChangedAt":"2026-09-18T22:14:11.667Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}