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

Correct the variable to the plain numeric format expected (the panic message names the variable).

invalid value for

Error message

invalid value for {name}: {x}

What it means

parse_env_var in cloud/options.rs parses retry/backoff-related env vars consumed when building object_store's BackoffConfig/RetryConfig, panicking with 'invalid value for {name}: {x}' when the value cannot be parsed into the target type. This runs while constructing cloud storage options for S3/GCS/Azure clients.

Solutions

Correct the variable to the plain numeric format expected (the panic message names the variable).
Unset it so the object_store default retry/backoff configuration applies.
Cross-check against object_store::RetryConfig documentation for valid value shapes.
Ensure upstream CI steps do not export empty strings; use conditional export only when a value exists.

Example fix

// before
export POLARS_RETRY_TIMEOUT=30s
// after
export POLARS_RETRY_TIMEOUT=30

Defensive patterns

Strategy: validation

Validate before calling

// Validate retry-related env vars before building storage options
fn check_retry_env(name: &str) {
    if let Ok(v) = std::env::var(name) {
        if v.trim().parse::<u64>().is_err() {
            panic!("{name} must be a plain number, got {v:?}");
        }
    }
}

Prevention

Use plain numbers for retry counts/timeouts, not Duration strings like '30s'.
Ensure CI exports nothing (not empty strings) when optional values are missing.
After Polars upgrades, re-check that variable names/types still match.

When it happens

Trigger: Setting a retry/backoff env var (timeouts, retry counts, backoff durations) to a value that fails FromStr — e.g. '5s' where a u64 is expected, 'true' where a number is expected, or empty strings.

Common situations: Mixing up duration conventions (seconds vs milliseconds vs Duration strings) between object_store and Polars; CI variables exported empty when a secret/parameter is missing; upgrading Polars and reusing old variable names with different types.

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/b3f4633e18f797fd. Report an issue: GitHub.

Appendix: source

Thrown at crates/polars-io/src/cloud/options.rs:212

                    )),
                    max_backoff: Duration::from_millis(parse_env_var(
                        5 * 1000,
                        "POLARS_CLOUD_RETRY_MAX_BACKOFF_MS",
                    )),
                    base: parse_env_var(2., "POLARS_CLOUD_RETRY_BASE_MULTIPLIER"),
                },
                max_retries: parse_env_var(8, "POLARS_CLOUD_MAX_RETRIES"),
                retry_timeout: Duration::from_millis(parse_env_var(
                    30 * 1000,
                    "POLARS_CLOUD_RETRY_TIMEOUT_MS",
                )),
            });

        fn parse_env_var<T: FromStr>(default: T, name: &'static str) -> T {
            std::env::var(name).map_or(default, |x| {
                x.parse::<T>()
                    .ok()
                    .unwrap_or_else(|| panic!("invalid value for {name}: {x}"))
            })
        }
    }
}

/// Rate-limit config publicly exposed through storage_options.
#[derive(Clone, Copy, Default, Debug, PartialEq, Hash, Eq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[cfg_attr(feature = "dsl-schema", derive(schemars::JsonSchema))]
pub struct CloudDirectionalRateLimitConfig {
    pub init_rate: Option<u64>,
    pub floor_rate: Option<u64>,
    pub ceiling_rate: Option<u64>,
}

#[derive(Clone, Copy, Default, Debug, PartialEq, Hash, Eq)]
#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
#[cfg_attr(feature = "dsl-schema", derive(schemars::JsonSchema))]

View on GitHub (pinned to fe841f959e)