{"record":{"id":"32a37755204199f0","repo":"pola-rs/polars","slug":"invalid-value-for-polars-cloud-writer-copy-buffer","errorCode":null,"errorMessage":"invalid value for POLARS_CLOUD_WRITER_COPY_BUFFER_SIZE: {s}","messagePattern":"invalid value for POLARS_CLOUD_WRITER_COPY_BUFFER_SIZE: (.+?)","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/polars-io/src/configs.rs","lineNumber":73,"sourceCode":"        }\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\") {\n            v = s.parse::<NonZeroUsize>().unwrap_or_else(|_| {\n                panic!(\"invalid value for POLARS_CLOUD_WRITER_COPY_BUFFER_SIZE: {s}\")\n            })\n        }\n\n        if polars_core::config::verbose() {\n            eprintln!(\"cloud_writer copy_buffer_size: {v}\")\n        }\n\n        v\n    });\n}\n","sourceCodeStart":55,"sourceCodeEnd":84,"githubUrl":"https://github.com/pola-rs/polars/blob/9b5d73fd00236295624374b075d16b1fe6ec6df9/crates/polars-io/src/configs.rs#L55-L84","documentation":"cloud_writer_copy_buffer_size() sizes the staging copy buffer for cloud uploads from POLARS_CLOUD_WRITER_COPY_BUFFER_SIZE, defaulting to 16 MiB. The string must parse as a NonZeroUsize, so 0 and any non-numeric value panic; unlike the coalesce knob there is no >= 2 filter, so 1 is technically accepted. The LazyLock means the panic happens on the first cloud write that touches the buffer, not when the variable is set.","triggerScenarios":"Setting POLARS_CLOUD_WRITER_COPY_BUFFER_SIZE=0 (a common attempt to 'disable' buffering to save memory), a value with a unit suffix (\"16M\"), scientific notation (\"1e6\"), or any non-number, then triggering the first cloud write that copies data through the buffer.","commonSituations":"Memory-tuning attempts on containers with tight limits; templates that mangle numbers (quotes, spaces, suffixes); values copied from docs of a different tool.","solutions":["Set a plain positive integer of bytes, e.g. export POLARS_CLOUD_WRITER_COPY_BUFFER_SIZE=16777216","Or unset the variable to use the 16 MiB default","Remember 0 is impossible by design (NonZeroUsize) - to lower memory pick a smaller positive size such as 1048576"],"exampleFix":"# before (0 is rejected by NonZeroUsize)\nexport POLARS_CLOUD_WRITER_COPY_BUFFER_SIZE=0\n\n# after\nexport POLARS_CLOUD_WRITER_COPY_BUFFER_SIZE=16777216   # 16 MiB\n# or: unset POLARS_CLOUD_WRITER_COPY_BUFFER_SIZE","handlingStrategy":"validation","validationCode":"fn validate_polars_env() -> Result<(), String> {\n    if let Ok(s) = std::env::var(\"POLARS_CLOUD_WRITER_COPY_BUFFER_SIZE\") {\n        if s.parse::<std::num::NonZeroUsize>().is_err() {\n            return Err(format!(\n                \"POLARS_CLOUD_WRITER_COPY_BUFFER_SIZE must be a non-zero integer of bytes, got {s:?}\"\n            ));\n        }\n    }\n    Ok(())\n}\n// call once at startup, before the first cloud write","typeGuard":null,"tryCatchPattern":"Deterministic LazyLock panic: wrap the first cloud write in catch_unwind only to convert it into a clean startup error; the real fix is correcting or unsetting the variable.","preventionTips":["Never set 0 for buffer knobs - check each knob's type (usize vs NonZeroUsize) before tuning","Template env values through one validated config module","Add a smoke cloud-write to CI with the production env vars"],"tags":["polars","polars-io","environment-variable","cloud-writer","memory","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-14T00:17:10.932Z"}