pola-rs/polars · error

invalid value for

Error message

invalid value for {NAME}: {x}

What it means

The gather/rechunk ratio used internally by gather operations is configurable through the POLARS_GATHER_RECHUNK_RATIO environment variable and must parse as a usize. If the variable is set to something unparseable (e.g. "64.0", "fast", empty string), gather_ratio panics with this message instead of silently falling back.

Solutions

1. Set POLARS_GATHER_RECHUNK_RATIO to a plain positive integer, e.g. 64
2. Unset the variable (delete/export -n) to fall back to the built-in default of 64
3. Fix the value in whichever startup script/CI config exports it

Example fix

// before
export POLARS_GATHER_RECHUNK_RATIO=0.5   # panics
// after
export POLARS_GATHER_RECHUNK_RATIO=32

if let Ok(v) = std::env::var("POLARS_GATHER_RECHUNK_RATIO") {
    if v.parse::<usize>().is_err() { return Err(format!("POLARS_GATHER_RECHUNK_RATIO must be a usize, got {v}")); }
}

When it happens

Trigger: Setting env var POLARS_GATHER_RECHUNK_RATIO to a non-integer string, then running any operation that triggers gather (take/join/groupby internals that call should_rechunk).

Common situations: Typos in tuning configs, copying a fractional or suffixed value ('0.5', '64M'), or exporting the variable empty in a shell profile.

Understand the failure class

Background: "is not a valid" / "Invalid ... value" environment variable errors: how libraries validate env vars and what to do when they reject yours — this error's family across 48 libraries.

Related errors

• could not parse table width argument
• creating extension types not allowed - try setting the…
• invalid value for POLARS_NDJSON_CHUNK_SIZE
• {0}
• activate dtype

AI-assisted analysis of pola-rs/polars@fe841f959e (2026-09-18). Data as JSON: /api/errors/a7a0c4049d81d926. Report an issue: GitHub.

Appendix: source

Thrown at crates/polars-core/src/chunked_array/ops/gather.rs:463

impl<I: AsRef<[IdxSize]> + ?Sized> ChunkTakeUnchecked<I> for ListChunked {
    unsafe fn take_unchecked(&self, indices: &I) -> Self {
        let idx = IdxCa::mmap_slice(PlSmallStr::EMPTY, indices.as_ref());
        self.take_unchecked(&idx)
    }
}

fn should_rechunk(n_values: usize, n_indices: usize) -> bool {
    n_indices > 0 && { (n_values / n_indices) > gather_ratio() }
}

fn gather_ratio() -> usize {
    return *GATHER_RECHUNK_RATIO.get_or_init(|| {
        const NAME: &str = "POLARS_GATHER_RECHUNK_RATIO";
        std::env::var(NAME)
            .map(|x| {
                x.parse::<usize>()
                    .unwrap_or_else(|_| panic!("invalid value for {NAME}: {x}"))
            })
            .unwrap_or(const { 64 })
    });

    static GATHER_RECHUNK_RATIO: OnceLock<usize> = OnceLock::new();
}

View on GitHub (pinned to fe841f959e)