pola-rs/polars · error

invalid value for POLARS_IGNORE_FILE_CACHE_ALLOCATE_ERROR

Error message

invalid value {v} for POLARS_IGNORE_FILE_CACHE_ALLOCATE_ERROR

What it means

POLARS_IGNORE_FILE_CACHE_ALLOCATE_ERROR only accepts '0' or '1'; any other non-empty value panics. The flag decides whether fallocate errors during cache file creation are ignored. The check runs once inside a LazyLock during try_open_check_latest.

Solutions

1. Set the variable to '1' (ignore allocate errors) or '0' (raise them)
2. Unset the variable entirely for the default behavior
3. Audit shell profiles/CI config for accidental values like 'true'

Example fix

// before
POLARS_IGNORE_FILE_CACHE_ALLOCATE_ERROR=true
// after
POLARS_IGNORE_FILE_CACHE_ALLOCATE_ERROR=1

if let Ok(v) = std::env::var("POLARS_IGNORE_FILE_CACHE_ALLOCATE_ERROR") {
    assert!(v == "0" || v == "1", "POLARS_IGNORE_FILE_CACHE_ALLOCATE_ERROR must be '0' or '1', got: {v}");
}

fn is_valid_alloc_flag(v: &str) -> bool {
    v == "0" || v == "1"
}

When it happens

Trigger: Setting POLARS_IGNORE_FILE_CACHE_ALLOCATE_ERROR to anything other than '0' or '1' (e.g. 'true', 'false', 'yes') and then opening a cached cloud file (try_open_assume_latest path).

Common situations: Developers using boolean-ish words like 'true'/'false' which the parser rejects; only the literal strings '0' and '1' are valid.

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

• integer
• in-flight byte budget init must be larger than the…
• integer
• invalid `POLARS_MAX_CACHED_METADATA_SCANS` value
• invalid value for

AI-assisted analysis of pola-rs/polars@fe841f959e (2026-09-18). Data as JSON: /api/errors/d7198981926023f3. Report an issue: GitHub.

Appendix: source

Thrown at crates/polars-io/src/file_cache/entry.rs:171

        let _ = std::fs::remove_file(data_file_path);
        if !self.file_fetcher.fetches_as_symlink() {
            let file = std::fs::OpenOptions::new()
                .write(true)
                .create(true)
                .truncate(true)
                .open(data_file_path)
                .map_err(PolarsError::from)?;

            // * Some(true)   => always raise
            // * Some(false)  => never raise
            // * None         => do not raise if fallocate() is not permitted, otherwise raise.
            static RAISE_ALLOC_ERROR: LazyLock<Option<bool>> = LazyLock::new(|| {
                let v = match std::env::var("POLARS_IGNORE_FILE_CACHE_ALLOCATE_ERROR").as_deref() {
                    Ok("1") => Some(false),
                    Ok("0") => Some(true),
                    Err(_) => None,
                    Ok(v) => {
                        panic!("invalid value {v} for POLARS_IGNORE_FILE_CACHE_ALLOCATE_ERROR")
                    },
                };
                if config::verbose() {
                    eprintln!("[file_cache]: RAISE_ALLOC_ERROR: {v:?}");
                }
                v
            });

            // Initialize it to get the verbose print
            let raise_alloc_err = *RAISE_ALLOC_ERROR;

            file.lock().unwrap();
            if let Err(e) = file.allocate(remote_metadata.size) {
                let msg = format!(
                    "failed to reserve {} bytes on disk to download uri = {}: {:?}",
                    remote_metadata.size, self.uri, e
                );

View on GitHub (pinned to fe841f959e)