{"record":{"id":"ec2d210d83404747","repo":"pola-rs/polars","slug":"invalid-value-for-polars-force-pkg-variable","errorCode":null,"errorMessage":"Invalid value for `POLARS_FORCE_PKG` variable: '{_force}'","messagePattern":"Invalid value for `POLARS_FORCE_PKG` variable: '(.+?)'","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/_plr.py","lineNumber":65,"sourceCode":"    # Each of the Polars variants registers a `_polars...` package that we can import\n    # the PLR from.\n\n    _force = os.environ.get(\"POLARS_FORCE_PKG\")\n    _prefer = os.environ.get(\"POLARS_PREFER_PKG\")\n\n    pkgs = {\"compat\": rt_compat, \"64\": rt_64, \"32\": rt_32}\n    default_prefer = [rt_compat, rt_64, rt_32]\n\n    if _force is not None:\n        try:\n            pkgs[_force]()\n\n            if sys.modules[__name__].__version__ != PKG_VERSION:\n                msg = f\"Polars Rust module for '{_force}' ({sys.modules[__name__].__version__}) did not match version of Python package '{PKG_VERSION}'\"\n                raise ImportError(msg)\n        except KeyError:\n            msg = f\"Invalid value for `POLARS_FORCE_PKG` variable: '{_force}'\"\n            raise ValueError(msg) from None\n    else:\n        preference = default_prefer\n        if _prefer is not None:\n            try:\n                preference.insert(0, pkgs[_prefer])\n            except KeyError:\n                msg = f\"Invalid value for `POLARS_PREFER_PKG` variable: '{_prefer}'\"\n                raise ValueError(msg) from None\n\n        version_warnings = []\n        for pkg in preference:\n            try:\n                pkg()\n\n                if sys.modules[__name__].__version__ != PKG_VERSION:\n                    import warnings\n\n                    version_warnings += [sys.modules[__name__].__version__]","sourceCodeStart":47,"sourceCodeEnd":83,"githubUrl":"https://github.com/pola-rs/polars/blob/df599052daf96e7a9cc30a3b0c6bd25d6947e3c0/py-polars/src/polars/_plr.py#L47-L83","documentation":"POLARS_FORCE_PKG selects which bundled Rust runtime polars loads; the only valid values are the dict keys 'compat', '64', and '32' (mapping to the `_polars_runtime_compat`/`_polars_runtime_64`/`_polars_runtime_32` packages). Any other string causes a KeyError that is re-raised as this ValueError at import time.","triggerScenarios":"`POLARS_FORCE_PKG=cpu64 python -c \"import polars\"`, or any value outside {'compat','64','32'} — including trailing whitespace from .env files (`POLARS_FORCE_PKG='64 '`) and shell quoting mistakes.","commonSituations":"Copy-pasting the variable from outdated blog posts or docs describing older polars mechanisms; typos; whitespace introduced by YAML/.env interpolation.","solutions":["Set the variable to a valid key: `export POLARS_FORCE_PKG=compat` (or '64'/'32')","Or unset it (`unset POLARS_FORCE_PKG`) to use default auto-selection","Check for stray whitespace/quotes: `printf '[%s]\\n' \"$POLARS_FORCE_PKG\"`"],"exampleFix":"# before\n# POLARS_FORCE_PKG=cpu64\nimport polars as pl  # ValueError: Invalid value for `POLARS_FORCE_PKG` variable: 'cpu64'\n\n# after\n# POLARS_FORCE_PKG=compat  (or '64'/'32')\nimport polars as pl","handlingStrategy":"validation","validationCode":"import os\n\nforce = os.environ.get(\"POLARS_FORCE_PKG\")\nif force is not None and force not in {\"compat\", \"64\", \"32\"}:\n    raise RuntimeError(f\"POLARS_FORCE_PKG={force!r} invalid — must be one of compat/64/32 or unset\")","typeGuard":"import os\n\ndef valid_force_pkg(value: str | None) -> bool:\n    return value is None or value in {\"compat\", \"64\", \"32\"}","tryCatchPattern":"try:\n    import polars as pl\nexcept ValueError as e:\n    if \"POLARS_FORCE_PKG\" in str(e):\n        import os; del os.environ[\"POLARS_FORCE_PKG\"]\n        import polars as pl  # noqa\n    else:\n        raise","preventionTips":["Validate both POLARS_FORCE_PKG and POLARS_PREFER_PKG against {'compat','64','32'} in a startup config check","Strip whitespace when loading env files (python-dotenv users see trailing-space bugs often)","Document the valid values next to wherever you set the variable (CI yaml, Dockerfile, .env)"],"tags":["environment-variables","configuration","import-time","rust-runtime"],"backgroundTag":null,"analyzedSha":"df599052daf96e7a9cc30a3b0c6bd25d6947e3c0","analyzedAt":"2026-08-16T12:10:03.978Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}