pola-rs/polars · error

invalid value for POLARS_NUM_READERS_PRE_INIT: {x}

Error message

invalid value for POLARS_NUM_READERS_PRE_INIT: {x}

What it means

Panic in calc_n_readers_pre_init: POLARS_NUM_READERS_PRE_INIT was set but cannot be parsed as a usize. The env var overrides how many multi-scan readers are initialized up front, so the unparsable value {x} panics before scan setup.

Source

Thrown at crates/polars-stream/src/nodes/io_sources/multi_scan/functions/mod.rs:23

use polars_io::cloud::CloudOptions;
use polars_io::cloud::concurrency_config::FetchConfig;
use polars_io::metrics::IOMetrics;
use polars_io::utils::byte_source::{ByteSource, DynByteSourceBuilder};
use polars_io::utils::compression::SupportedCompression;
use polars_plan::dsl::ScanSource;
use polars_utils::slice_enum::Slice;

pub mod resolve_projections;
pub mod resolve_slice;

pub fn calc_n_readers_pre_init(
    num_pipelines: usize,
    num_sources: usize,
    pre_slice: Option<&Slice>,
) -> usize {
    if let Ok(v) = std::env::var("POLARS_NUM_READERS_PRE_INIT").map(|x| {
        x.parse::<NonZeroUsize>()
            .unwrap_or_else(|_| panic!("invalid value for POLARS_NUM_READERS_PRE_INIT: {x}"))
            .get()
    }) {
        return v;
    }

    let max_files_with_slice = match pre_slice {
        // Calculate the max number of files assuming 1 row per file.
        Some(v @ Slice::Positive { .. }) => v.end_position().max(1),
        Some(Slice::Negative { .. }) | None => usize::MAX,
    };

    // Set this generously high, there are users who scan 10,000's of small files from the cloud.
    num_pipelines
        .saturating_add(3)
        .min(max_files_with_slice)
        .min(num_sources)
        .clamp(1, 128)
}

View on GitHub (pinned to 9b5d73fd00)

Solutions

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

Example fix

export POLARS_NUM_READERS_PRE_INIT=2

When it happens

Trigger: Invalid value in POLARS_NUM_READERS_PRE_INIT.

Common situations: See trigger scenarios.

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