pola-rs/polars · error

invalid value for POLARS_RECORD_BATCH_PREFETCH_KBYTES_BUDGET

Error message

invalid value for POLARS_RECORD_BATCH_PREFETCH_KBYTES_BUDGET: {x}

What it means

Panic in IpcReaderBuilder::set_execution_state: POLARS_RECORD_BATCH_PREFETCH_KBYTES_BUDGET was set but is not a valid NonZeroUsize. It overrides the kilobyte memory budget for the IPC prefetch pipeline; the invalid string {x} causes reader setup to abort.

Source

Thrown at crates/polars-stream/src/nodes/io_sources/ipc/builder.rs:75

                        panic!("invalid value for POLARS_RECORD_BATCH_PREFETCH_SIZE: {x}")
                    })
                    .get()
            })
            .unwrap_or(
                // Similar to Parquet.
                execution_state
                    .num_pipelines
                    .saturating_mul(2)
                    .max(get_request_budget() as usize)
                    .clamp(16, 2048),
            )
            .max(1);

        let prefetch_kbytes_limit = std::env::var("POLARS_RECORD_BATCH_PREFETCH_KBYTES_BUDGET")
            .map(|x| {
                x.parse::<NonZeroUsize>()
                    .unwrap_or_else(|_| {
                        panic!("invalid value for POLARS_RECORD_BATCH_PREFETCH_KBYTES_BUDGET: {x}")
                    })
                    .get()
            })
            .unwrap_or({
                // Similar to Parquet.
                let target_chunk_size_kb = FetchConfig::random_access().chunk_size.div_ceil(1024);
                4 * execution_state.num_pipelines * target_chunk_size_kb
            })
            // Avoid deadlock.
            .max(polars_io::cloud::concurrency_config::get_download_chunk_size().div_ceil(1024));

        if config::verbose() {
            eprintln!(
                "[IpcReaderBuilder]: prefetch_limit: {}, prefetch_kbytes_limit: {}",
                prefetch_limit, prefetch_kbytes_limit
            );
        }

View on GitHub (pinned to 9b5d73fd00)

Solutions

1. Set POLARS_RECORD_BATCH_PREFETCH_KBYTES_BUDGET to a positive integer or unset it.

Example fix

export POLARS_RECORD_BATCH_PREFETCH_KBYTES_BUDGET=65536

When it happens

Trigger: Invalid value in POLARS_RECORD_BATCH_PREFETCH_KBYTES_BUDGET.

Common situations: See trigger scenarios.

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