{"record":{"id":"01bf2918cfb4aa31","repo":"pola-rs/polars","slug":"invalid-value-for-polars-prefer-pkg-variable","errorCode":null,"errorMessage":"Invalid value for `POLARS_PREFER_PKG` variable: '{_prefer}'","messagePattern":"Invalid value for `POLARS_PREFER_PKG` variable: '(.+?)'","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"py-polars/src/polars/_plr.py","lineNumber":73,"sourceCode":"\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__]\n                    warnings.warn(\n                        f\"Skipping Polars' Rust module version '{sys.modules[__name__].__version__}' did not match version of Python package '{PKG_VERSION}'.\",\n                        ImportWarning,\n                        stacklevel=2,\n                    )\n                    continue\n\n                break","sourceCodeStart":55,"sourceCodeEnd":91,"githubUrl":"https://github.com/pola-rs/polars/blob/df599052daf96e7a9cc30a3b0c6bd25d6947e3c0/py-polars/src/polars/_plr.py#L55-L91","documentation":"POLARS_PREFER_PKG moves one Rust runtime package to the front of the preference list polars tries at import; valid values are the dict keys 'compat', '64', '32'. Any other value causes a KeyError when indexing `pkgs[_prefer]`, re-raised as this ValueError at import time. Unlike FORCE, an invalid PREFER fails immediately rather than falling back to defaults.","triggerScenarios":"`POLARS_PREFER_PKG=x86_64 python -c \"import polars\"` or any value outside {'compat','64','32'}, including whitespace or quoting artifacts from environment files or CI matrix variables.","commonSituations":"Env vars carried over from older polars versions or other projects; CI configuration with interpolated values that expand to empty/invalid strings; typos.","solutions":["Set the variable to a valid key: `export POLARS_PREFER_PKG=64` (or 'compat'/'32')","Or unset it (`unset POLARS_PREFER_PKG`) to keep the default preference order compat -> 64 -> 32","Echo the raw value to catch whitespace/quotes: `printf '[%s]\\n' \"$POLARS_PREFER_PKG\"`"],"exampleFix":"# before\n# POLARS_PREFER_PKG=cpu64\nimport polars as pl  # ValueError: Invalid value for `POLARS_PREFER_PKG` variable: 'cpu64'\n\n# after\n# POLARS_PREFER_PKG=64\nimport polars as pl","handlingStrategy":"validation","validationCode":"import os\n\nprefer = os.environ.get(\"POLARS_PREFER_PKG\")\nif prefer is not None and prefer not in {\"compat\", \"64\", \"32\"}:\n    raise RuntimeError(f\"POLARS_PREFER_PKG={prefer!r} invalid — must be one of compat/64/32 or unset\")","typeGuard":"import os\n\ndef valid_prefer_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_PREFER_PKG\" in str(e):\n        import os; del os.environ[\"POLARS_PREFER_PKG\"]\n        import polars as pl  # noqa\n    else:\n        raise","preventionTips":["Run a startup env sanitizer that whitelists POLARS_* variables and their values","Watch CI matrix interpolations that can produce empty or invalid values for POLARS_PREFER_PKG","Prefer unset (default order compat -> 64 -> 32) unless a specific variant is required"],"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"}