pola-rs/polars · error

integer

Error message

integer

What it means

get_env_file_cache_ttl parses POLARS_FILE_CACHE_TTL as a u64 and panics with 'integer' if parsing fails. The variable controls the file cache TTL in seconds (default 3600). This is an env-var validation guard.

Solutions

1. Set POLARS_FILE_CACHE_TTL to a plain integer of seconds, e.g. '3600'
2. Unset the variable to use the default 60*60 seconds
3. Convert any duration formatting (e.g. '1h') to seconds in your env setup

Example fix

// before
POLARS_FILE_CACHE_TTL=1h
// after
POLARS_FILE_CACHE_TTL=3600

if let Ok(v) = std::env::var("POLARS_FILE_CACHE_TTL") {
    v.parse::<u64>().unwrap_or_else(|_| panic!("POLARS_FILE_CACHE_TTL must be a u64 number of seconds, got: {v}"));
}

fn is_valid_cache_ttl(v: &str) -> bool {
    v.parse::<u64>().is_ok()
}

When it happens

Trigger: Setting POLARS_FILE_CACHE_TTL to a non-numeric or negative value (e.g. '1h', '-1', 'one hour') before a cloud file-cache operation via CloudOptions.

Common situations: Users assuming the value accepts duration strings like '60s' or '1h'; the parser only accepts bare unsigned integers (seconds).

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

• invalid value for POLARS_IGNORE_FILE_CACHE_ALLOCATE_ERROR
• 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/2e6fcf4bcecd855c. Report an issue: GitHub.

Appendix: source

Thrown at crates/polars-io/src/file_cache/cache.rs:173

            Ok(entry)
        }
    }

    /// This function can accept relative local paths.
    pub fn get_entry(&self, path: PlRefPath) -> Option<Arc<FileCacheEntry>> {
        if path.has_scheme() {
            self.entries.read().unwrap().get(&path).cloned()
        } else {
            let p =
                PlRefPath::try_from_pathbuf(std::fs::canonicalize(path.as_str()).unwrap()).unwrap();
            self.entries.read().unwrap().get(&p).cloned()
        }
    }
}

pub fn get_env_file_cache_ttl() -> u64 {
    std::env::var("POLARS_FILE_CACHE_TTL")
        .map(|x| x.parse::<u64>().expect("integer"))
        .unwrap_or(60 * 60)
}

View on GitHub (pinned to fe841f959e)