pola-rs/polars · error

invalid value for POLARS_PYTHON_SCAN_RESOLVE_THREADS

Error message

invalid value for POLARS_PYTHON_SCAN_RESOLVE_THREADS: {x}

What it means

PyScanResolveThreadPool::new reads POLARS_PYTHON_SCAN_RESOLVE_THREADS and parses it as NonZeroUsize; an unparseable or zero value makes the unwrap_or_else panic with this message naming the raw value. Set the env var to a positive integer or unset it for the default (128).

Solutions

1. Set POLARS_PYTHON_SCAN_RESOLVE_THREADS to a valid positive integer.
2. Unset the variable to use the default thread count.

When it happens

Trigger: This panic/expect fires when execution reaches an unguarded state described by: "invalid value for POLARS_PYTHON_SCAN_RESOLVE_THREADS: {x}". Typical triggers: unsupported dtype or feature-gated code path reached at runtime, invalid user input or environment variable value, calling API methods in the wrong order or on mismatched types, or data (lengths, offsets, ranges) violating the function's preconditions.

Common situations: Encountered when input data or configuration does not meet the preconditions of the throwing code path ("invalid value for POLARS_PYTHON_SCAN_RESOLVE_THREADS: {x}"). Common cases: missing Cargo feature flags, mismatched dtypes/lengths between arrays or series, out-of-range temporal values, malformed environment variables, or operations on unsupported/complex nested types.

AI-assisted analysis of pola-rs/polars@fc24390824 (2026-08-19). Data as JSON: /api/errors/c1e24c29c067ef80. Report an issue: GitHub.

Appendix: source

Thrown at crates/polars-plan/src/plans/optimizer/expand_datasets.rs:513

        pyo3::IntoPyObject::into_pyobject(&self.0, py)
    }
}

#[cfg(feature = "python")]
impl PyScanResolveThreadPool {
    pub fn new() -> Self {
        use std::num::NonZeroUsize;
        use std::sync::LazyLock;

        use pyo3::types::PyAnyMethods;
        use pyo3::{Py, PyAny, PyResult, Python};

        Python::attach(|py| {
            let num_threads =
                std::env::var("POLARS_PYTHON_SCAN_RESOLVE_THREADS").map_or(128, |x| {
                    x.parse::<NonZeroUsize>()
                        .unwrap_or_else(|_| {
                            panic!("invalid value for POLARS_PYTHON_SCAN_RESOLVE_THREADS: {x}")
                        })
                        .get()
                });

            if polars_config::config().verbose() {
                eprintln!("python scan_resolve_threadpool threads: {num_threads}")
            }

            if LazyLock::get(&PY_SCAN_RESOLVE_THREADPOOL_CLS).is_none() {
                py.detach(|| LazyLock::force(&PY_SCAN_RESOLVE_THREADPOOL_CLS));
            }

            return Self(
                PY_SCAN_RESOLVE_THREADPOOL_CLS
                    .bind(py)
                    .call1((num_threads,))
                    .map(|x| x.unbind())
                    .unwrap(),

View on GitHub (pinned to fc24390824)