pola-rs/polars · error

invalid value for POLARS_RECORD_BATCH_PREFETCH_SIZE: {x}

Error message

invalid value for POLARS_RECORD_BATCH_PREFETCH_SIZE: {x}

What it means

Panic in IpcReaderBuilder::set_execution_state: POLARS_RECORD_BATCH_PREFETCH_SIZE was set but is not a valid NonZeroUsize. The env var overrides the default number of prefetched record batches, so the unparsable value {x} aborts reader initialization.

Source

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

#[cfg(feature = "ipc")]
impl FileReaderBuilder for IpcReaderBuilder {
    fn reader_name(&self) -> &str {
        "ipc"
    }

    fn reader_capabilities(&self) -> ReaderCapabilities {
        use ReaderCapabilities as RC;

        RC::ROW_INDEX | RC::PRE_SLICE
    }

    fn set_execution_state(&self, execution_state: &crate::execute::StreamingExecutionState) {
        let prefetch_limit = std::env::var("POLARS_RECORD_BATCH_PREFETCH_SIZE")
            .map(|x| {
                x.parse::<NonZeroUsize>()
                    .unwrap_or_else(|_| {
                        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}")

View on GitHub (pinned to 9b5d73fd00)

Solutions

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

Example fix

export POLARS_RECORD_BATCH_PREFETCH_SIZE=8

When it happens

Trigger: Invalid value in POLARS_RECORD_BATCH_PREFETCH_SIZE.

Common situations: See trigger scenarios.

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