invalid value for POLARS_CLOUD_WRITER_COALESCE_RUN_LENGTH: {

Error message

invalid value for POLARS_CLOUD_WRITER_COALESCE_RUN_LENGTH: {s}

What it means

Polars' cloud writer reads POLARS_CLOUD_WRITER_COALESCE_RUN_LENGTH once per process (through a LazyLock) to choose how many buffered chunks are coalesced per cloud write; the default is 64. The value must parse as a Rust usize AND pass the .filter(|x| *x >= 2) check, so 0 and 1 are rejected even though they are valid integers. Because the check lives in a lazy static, the panic fires on the first cloud write of the process, not when the variable is set, which makes the bad value easy to misdiagnose.

Source

Thrown at crates/polars-io/src/configs.rs:53

            })
        })
}

/// Runs of this many values whose total bytes are <= `copy_buffer_reserve_size` will be copied into
/// a single contiguous chunk.
pub(crate) fn cloud_writer_coalesce_run_length() -> usize {
    return *COALESCE_RUN_LENGTH;

    static COALESCE_RUN_LENGTH: LazyLock<usize> = LazyLock::new(|| {
        let mut v: usize = 64;

        if let Ok(s) = std::env::var("POLARS_CLOUD_WRITER_COALESCE_RUN_LENGTH") {
            v = s
                .parse::<usize>()
                .ok()
                .filter(|x| *x >= 2)
                .unwrap_or_else(|| {
                    panic!("invalid value for POLARS_CLOUD_WRITER_COALESCE_RUN_LENGTH: {s}")
                })
        }

        if polars_core::config::verbose() {
            eprintln!("cloud_writer coalesce_run_length: {v}")
        }

        v
    });
}

pub(crate) fn cloud_writer_copy_buffer_size() -> NonZeroUsize {
    return *COPY_BUFFER_SIZE;

    static COPY_BUFFER_SIZE: LazyLock<NonZeroUsize> = LazyLock::new(|| {
        let mut v: NonZeroUsize = const { NonZeroUsize::new(16 * 1024 * 1024).unwrap() };

        if let Ok(s) = std::env::var("POLARS_CLOUD_WRITER_COPY_BUFFER_SIZE") {

View on GitHub (pinned to 9b5d73fd00)

Solutions

Set the variable to an integer >= 2, e.g. export POLARS_CLOUD_WRITER_COALESCE_RUN_LENGTH=64
Or unset it to fall back to the built-in default of 64
If you wanted to disable coalescing, note there is no valid value below 2 - tune POLARS_CLOUD_WRITER_COPY_BUFFER_SIZE instead

Example fix

# before (panics on first cloud write)
export POLARS_CLOUD_WRITER_COALESCE_RUN_LENGTH=1

# after
export POLARS_CLOUD_WRITER_COALESCE_RUN_LENGTH=64
# or simply: unset POLARS_CLOUD_WRITER_COALESCE_RUN_LENGTH

Defensive patterns

Strategy: validation

Validate before calling

fn validate_polars_env() -> Result<(), String> {
    if let Ok(s) = std::env::var("POLARS_CLOUD_WRITER_COALESCE_RUN_LENGTH") {
        match s.parse::<usize>() {
            Ok(v) if v >= 2 => {},
            _ => return Err(format!(
                "POLARS_CLOUD_WRITER_COALESCE_RUN_LENGTH must be an integer >= 2, got {s:?}"
            )),
        }
    }
    Ok(())
}
// call once at process startup, before the first cloud write

Try / catch

The panic comes from a LazyLock deep in the writer; the only in-process catch is std::panic::catch_unwind(AssertUnwindSafe(|| lf.sink_parquet(url, opts))). It is a deterministic config bug: catch only to print a clean message, then fix the env var - retrying never succeeds.

Prevention

Validate every POLARS_* tuning variable in one config step at process start
Log the effective values of all tuning env vars at boot so bad values surface immediately
Run one cloud-write integration test in CI so config errors fail the build, not production

When it happens

Trigger: Exporting POLARS_CLOUD_WRITER_COALESCE_RUN_LENGTH as a non-integer ("64.0", "64 ", "sixty", empty string) or as 0 or 1, then performing the first buffered cloud write (e.g. sinking a LazyFrame to an s3:// or az:// URL), which initializes COALESCE_RUN_LENGTH for the first time via cloud_writer_coalesce_run_length().

Common situations: CI/Helm/env-template systems that inject quoted or empty values for tuning knobs; copying tuning advice written for another tool or polars version; setting 1 hoping to switch coalescing off.

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

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