{"record":{"id":"e01b281e48d0f602","repo":"pola-rs/polars","slug":"unknown-physical-dtype","errorCode":null,"errorMessage":"unknown physical dtype","messagePattern":"unknown physical dtype","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/datatypes/classes.py","lineNumber":837,"sourceCode":"        \"\"\"The name of this `Categories`.\"\"\"\n        return self._categories.name()\n\n    def namespace(self) -> str:\n        \"\"\"The namespace of this `Categories`.\"\"\"\n        return self._categories.namespace()\n\n    def physical(self) -> PolarsDataType:\n        \"\"\"The physical type used to represent the categories.\"\"\"\n        phys = self._categories.physical()\n        if phys == \"u8\":\n            return pldt.UInt8\n        elif phys == \"u16\":\n            return pldt.UInt16\n        elif phys == \"u32\":\n            return pldt.UInt32\n        else:\n            msg = \"unknown physical dtype\"\n            raise RuntimeError(msg)\n\n    def is_global(self) -> bool:\n        \"\"\"Returns whether this refers to the global categories.\"\"\"\n        return self._categories.is_global()\n\n    def __getitem__(self, key: str | int) -> str | int:\n        if isinstance(key, str):\n            if (cat := self._categories.get_cat(key)) is None:\n                raise KeyError(key)\n            return cat\n        elif isinstance(key, int):\n            if (s := self._categories.cat_to_str(key)) is None:\n                msg = f\"category index out of range: {key}\"\n                raise IndexError(msg)\n            return s\n        else:\n            msg = f\"invalid key type {type(key)}; expected str or int\"\n            raise TypeError(msg)","sourceCodeStart":819,"sourceCodeEnd":855,"githubUrl":"https://github.com/pola-rs/polars/blob/fe841f959ef4d2ceefc05a310d33ed7b1ab24e5e/py-polars/src/polars/datatypes/classes.py#L819-L855","documentation":"The Categories.physical property converts the internal physical code (a string like 'u8'/'u16'/'u32') back to a Polars dtype. If the internal value is anything else, the invariant is broken, so a RuntimeError is raised. This normally indicates an internal bug rather than a user error.","triggerScenarios":"Reading categories.physical on a Categories object whose underlying PyCategories carries an unrecognized physical code — practically only reachable through internal inconsistencies, version mismatch between Rust core and Python bindings, or deserialization of foreign data.","commonSituations":"Mixed-version py-polars installs where the Rust binary and Python layer disagree; custom/manual construction of Categories objects; corrupted caches.","solutions":["Reinstall/upgrade py-polars so the Python layer and compiled Rust core match","Avoid constructing Categories objects manually; only use pl.Categorical(...)","If reproducible, file a bug with a minimal reproducer"],"exampleFix":"// before (mixed versions)\nimport polars  # rust core 1.x, python 1.y\n// after\npip install --upgrade --force-reinstall polars","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try:\n    dt = categories.physical\nexcept RuntimeError:\n    dt = None  # handle inconsistent state, rebuild Categories","preventionTips":["Keep py-polars Python and Rust components version-matched (single pip install)","Never construct Categories internals manually","Recreate Categories objects via pl.Categorical after upgrades"],"tags":["polars","categorical","runtime-error","internal"],"backgroundTag":"internal-invariant-violation","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"}