{"record":{"id":"260024f2ee96f53f","repo":"pola-rs/polars","slug":"invalid-value-for-polars-python-scan-resolve-threa-260024","errorCode":null,"errorMessage":"invalid value for POLARS_PYTHON_SCAN_RESOLVE_THREADS: {x}","messagePattern":"invalid value for POLARS_PYTHON_SCAN_RESOLVE_THREADS: (.+?)","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/polars-utils/src/python_thread_pool.rs","lineNumber":31,"sourceCode":"    type Output = <&'py Py<PyAny> as IntoPyObject<'py>>::Output;\n    type Target = <&'py Py<PyAny> as IntoPyObject<'py>>::Target;\n    type Error = <&'py Py<PyAny> as IntoPyObject<'py>>::Error;\n\n    fn into_pyobject(self, py: Python<'py>) -> Result<Self::Output, Self::Error> {\n        IntoPyObject::into_pyobject(&self.0, py)\n    }\n}\n\nimpl PyThreadPool {\n    pub fn new() -> Self {\n        use std::num::NonZeroUsize;\n\n        Python::attach(|py| {\n            let num_threads =\n                std::env::var(\"POLARS_PYTHON_SCAN_RESOLVE_THREADS\").map_or(128, |x| {\n                    x.parse::<NonZeroUsize>()\n                        .unwrap_or_else(|_| {\n                            panic!(\"invalid value for POLARS_PYTHON_SCAN_RESOLVE_THREADS: {x}\")\n                        })\n                        .get()\n                });\n\n            if polars_config::config().verbose() {\n                eprintln!(\"python scan_resolve_threadpool threads: {num_threads}\")\n            }\n\n            return Self(\n                py_scan_resolve_threadpool_cls(py)\n                    .bind(py)\n                    .call1((num_threads,))\n                    .map(|x| x.unbind())\n                    .unwrap(),\n            );\n\n            fn py_scan_resolve_threadpool_cls(py: Python<'_>) -> &'static Py<PyAny> {\n                static CLS: PyOnceLock<Py<PyAny>> = PyOnceLock::new();","sourceCodeStart":13,"sourceCodeEnd":49,"githubUrl":"https://github.com/pola-rs/polars/blob/68506541d2de983056c9eb244e1ea05fab377dfc/crates/polars-utils/src/python_thread_pool.rs#L13-L49","documentation":"Polars reads the environment variable POLARS_PYTHON_SCAN_RESOLVE_THREADS once, when lazily initializing the Python scan-resolve thread pool, and requires it to parse as a non-zero usize. Any other value (empty string, non-numeric, 0) aborts initialization with this panic. Valid values control how many threads the scan resolution thread pool uses (default 128).","triggerScenarios":"Setting POLARS_PYTHON_SCAN_RESOLVE_THREADS in the environment or process env to anything not parseable by `usize::from_str` as a NonZeroUsize — e.g. `\"0\"`, `\"\"`, `\"abc\"`, `\"12.5\"`, `\"1_000\"` — and then executing the first Python-scan operation that initializes the pool.","commonSituations":"Copy-pasted config with typos, quoting artifacts from shell profiles or container orchestration env files (`THREADS=128\\n`), setting 0 assuming it means 'unlimited', unit suffixes like `128k`, or locale-formatted numbers.","solutions":["Unset POLARS_PYTHON_SCAN_RESOLVE_THREADS to fall back to the default of 128.","Set it to a plain positive integer, e.g. `export POLARS_PYTHON_SCAN_RESOLVE_THREADS=64`.","Remove surrounding whitespace/quotes/BOM from the value in shell profiles, .env files, or k8s manifests.","Ensure the value is set before the Polars process starts; if set programmatically, set it via os.environ before the first scan."],"exampleFix":"// before\nPOLARS_PYTHON_SCAN_RESOLVE_THREADS=0\n// after\nPOLARS_PYTHON_SCAN_RESOLVE_THREADS=64","handlingStrategy":"validation","validationCode":"import os, re\nv = os.environ.get(\"POLARS_PYTHON_SCAN_RESOLVE_THREADS\")\nif v is not None and not (v.strip().isdigit() and int(v) > 0):\n    raise ValueError(f\"POLARS_PYTHON_SCAN_RESOLVE_THREADS must be a positive integer, got {v!r}\")","typeGuard":"def is_valid_thread_count(v: str | None) -> bool:\n    return v is None or (v.strip().isdigit() and int(v) > 0)","tryCatchPattern":null,"preventionTips":["Only set plain positive integers in env config","Sanitize env values (strip whitespace/quotes) in deployment manifests","Document that 0 is invalid — omit the variable for defaults","Validate env config at process startup, before the first scan"],"tags":["environment","configuration","rust","threading","panic"],"backgroundTag":"invalid-env-var-value","analyzedSha":"68506541d2de983056c9eb244e1ea05fab377dfc","analyzedAt":"2026-09-10T10:08:55.499Z","contentChangedAt":"2026-09-10T10:08:55.499Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}