{"record":{"id":"7212efa901644332","repo":"pola-rs/polars","slug":"invalid-value-for-polars-cloud-writer-coalesce-run","errorCode":null,"errorMessage":"invalid value for POLARS_CLOUD_WRITER_COALESCE_RUN_LENGTH: {s}","messagePattern":"invalid value for POLARS_CLOUD_WRITER_COALESCE_RUN_LENGTH: (.+?)","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/polars-io/src/configs.rs","lineNumber":53,"sourceCode":"            })\n        })\n}\n\n/// Runs of this many values whose total bytes are <= `copy_buffer_reserve_size` will be copied into\n/// a single contiguous chunk.\npub(crate) fn cloud_writer_coalesce_run_length() -> usize {\n    return *COALESCE_RUN_LENGTH;\n\n    static COALESCE_RUN_LENGTH: LazyLock<usize> = LazyLock::new(|| {\n        let mut v: usize = 64;\n\n        if let Ok(s) = std::env::var(\"POLARS_CLOUD_WRITER_COALESCE_RUN_LENGTH\") {\n            v = s\n                .parse::<usize>()\n                .ok()\n                .filter(|x| *x >= 2)\n                .unwrap_or_else(|| {\n                    panic!(\"invalid value for POLARS_CLOUD_WRITER_COALESCE_RUN_LENGTH: {s}\")\n                })\n        }\n\n        if polars_core::config::verbose() {\n            eprintln!(\"cloud_writer coalesce_run_length: {v}\")\n        }\n\n        v\n    });\n}\n\npub(crate) fn cloud_writer_copy_buffer_size() -> NonZeroUsize {\n    return *COPY_BUFFER_SIZE;\n\n    static COPY_BUFFER_SIZE: LazyLock<NonZeroUsize> = LazyLock::new(|| {\n        let mut v: NonZeroUsize = const { NonZeroUsize::new(16 * 1024 * 1024).unwrap() };\n\n        if let Ok(s) = std::env::var(\"POLARS_CLOUD_WRITER_COPY_BUFFER_SIZE\") {","sourceCodeStart":35,"sourceCodeEnd":71,"githubUrl":"https://github.com/pola-rs/polars/blob/9b5d73fd00236295624374b075d16b1fe6ec6df9/crates/polars-io/src/configs.rs#L35-L71","documentation":"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.","triggerScenarios":"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().","commonSituations":"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.","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"],"exampleFix":"# before (panics on first cloud write)\nexport POLARS_CLOUD_WRITER_COALESCE_RUN_LENGTH=1\n\n# after\nexport POLARS_CLOUD_WRITER_COALESCE_RUN_LENGTH=64\n# or simply: unset POLARS_CLOUD_WRITER_COALESCE_RUN_LENGTH","handlingStrategy":"validation","validationCode":"fn validate_polars_env() -> Result<(), String> {\n    if let Ok(s) = std::env::var(\"POLARS_CLOUD_WRITER_COALESCE_RUN_LENGTH\") {\n        match s.parse::<usize>() {\n            Ok(v) if v >= 2 => {},\n            _ => return Err(format!(\n                \"POLARS_CLOUD_WRITER_COALESCE_RUN_LENGTH must be an integer >= 2, got {s:?}\"\n            )),\n        }\n    }\n    Ok(())\n}\n// call once at process startup, before the first cloud write","typeGuard":null,"tryCatchPattern":"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.","preventionTips":["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"],"tags":["polars","polars-io","environment-variable","cloud-writer","panic","configuration"],"backgroundTag":"invalid-env-var-value","analyzedSha":"9b5d73fd00236295624374b075d16b1fe6ec6df9","analyzedAt":"2026-08-19T12:15:06.350Z","contentChangedAt":"2026-08-19T12:15:06.350Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}