What causes "invalid value for POLARS_CLOUD_FOOTER_READ_SIZE: {s}" in pola-rs/polars?

Set POLARS_CLOUD_FOOTER_READ_SIZE to a plain non-negative integer of bytes (e.g. 5242880) or unset it for the default

invalid value for POLARS_CLOUD_FOOTER_READ_SIZE

Error message

invalid value for POLARS_CLOUD_FOOTER_READ_SIZE: {s}

What it means

This panic fires when POLARS_CLOUD_FOOTER_READ_SIZE is set to a value that cannot be parsed as usize. The variable overrides how many bytes are read when fetching the footer of a remote Parquet file; cloud_footer_read_size parses it and panics on failure. If the variable is unset, a built-in default is returned instead, so only present-but-invalid values abort.

Solutions

Set POLARS_CLOUD_FOOTER_READ_SIZE to a plain non-negative integer of bytes (e.g. 5242880) or unset it for the default
Remove unit suffixes, decimals, and signs
If reading very large Parquet footers, increase the numeric value rather than reformatting it

Example fix

// before
export POLARS_CLOUD_FOOTER_READ_SIZE=5MB
// after
export POLARS_CLOUD_FOOTER_READ_SIZE=5242880

Defensive patterns

Strategy: validation

Validate before calling

const v = process.env.POLARS_CLOUD_FOOTER_READ_SIZE;
if (v !== undefined && !/^[0-9]+$/.test(v.trim())) throw new Error(`POLARS_CLOUD_FOOTER_READ_SIZE must be a non-negative integer of bytes, got: ${v}`);

Type guard

function isValidFooterReadSize(v) { return typeof v === 'string' && /^\d+$/.test(v.trim()); }

Try / catch

// sanitize before launch; usize parse rejects signs, units, decimals
const raw = process.env.POLARS_CLOUD_FOOTER_READ_SIZE;
if (raw && !/^\d+$/.test(raw.trim())) { console.error('POLARS_CLOUD_FOOTER_READ_SIZE must be plain bytes'); process.exit(2); }

Prevention

Use plain byte integers only
Unset the variable to use the default footer read size
Do not copy formats from other tools that accept size suffixes
Check remote Parquet reads (fetch_footer_bytes) when debugging

When it happens

Trigger: export POLARS_CLOUD_FOOTER_READ_SIZE=0 is accepted by usize parse (note: only parse failures panic), so the panic specifically comes from non-numeric strings like 'abc', '1MB', '-1024' (minus sign fails usize), or empty strings; triggered via fetch_footer_bytes or read_parquet_metadata_bytes on remote Parquet reads.

Common situations: Tuning remote Parquet metadata reads for very large footers and using unit suffixes; typos; values copied from a different Polars variable with different formatting rules.

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@fe841f959e (2026-09-18). Data as JSON: /api/errors/16830b0053cad8b9. Report an issue: GitHub.

Appendix: source

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

        }

        v
    });
}

/// Tail size to speculatively fetch when reading file metadata from a cloud source. Sized
/// generously as the cost of overfetching is low (extra KB) vs the cost of underfetching
/// (extra round-trip).
pub const DEFAULT_CLOUD_FOOTER_READ_SIZE: usize = 256 * 1024;

// Not cached - lookup cost is low compared to I/O, allows for testing.
pub fn cloud_footer_read_size() -> usize {
    let Ok(s) = std::env::var("POLARS_CLOUD_FOOTER_READ_SIZE") else {
        return DEFAULT_CLOUD_FOOTER_READ_SIZE;
    };

    s.parse::<usize>()
        .unwrap_or_else(|_| panic!("invalid value for POLARS_CLOUD_FOOTER_READ_SIZE: {s}"))
}

View on GitHub (pinned to fe841f959e)