invalid value for POLARS_HTTP_CONNECT_TIMEOUT_SECONDS

Error message

invalid value for POLARS_HTTP_CONNECT_TIMEOUT_SECONDS: {x}

What it means

When building cloud client options (build_aws/build_azure/build_gcp), Polars reads POLARS_HTTP_CONNECT_TIMEOUT_SECONDS as a NonZeroU64 to configure the HTTP connect timeout (default 300 seconds). A set-but-unparseable or zero value triggers this panic during storage client construction.

Solutions

Set the variable to a positive integer number of seconds, e.g. 300.
Unset it to use the default 5-minute connect timeout.
Use the timeout unit explicitly in the variable name — it is SECONDS, so convert durations before export.
If 'no timeout' is desired, use a very large integer rather than 0, since 0 is rejected.

Example fix

// before
export POLARS_HTTP_CONNECT_TIMEOUT_SECONDS=5min
// after
export POLARS_HTTP_CONNECT_TIMEOUT_SECONDS=300

Defensive patterns

Strategy: validation

Validate before calling

const v = process.env.POLARS_HTTP_CONNECT_TIMEOUT_SECONDS;
if (v !== undefined && (!/^[1-9]\d*$/.test(v.trim()) || BigInt(v) > 18446744073709551615n)) {
  throw new Error(`POLARS_HTTP_CONNECT_TIMEOUT_SECONDS must be a positive integer (seconds), got: ${JSON.stringify(v)}`);
}

Type guard

const isValidTimeoutSeconds = (v) => typeof v === 'string' && /^[1-9]\d*$/.test(v.trim());

Prevention

The unit is seconds — convert '5min' to 300 before export.
Zero is rejected; use a large integer or unset the variable for defaults.
Avoid duration formats from other HTTP libraries; this variable takes only integer seconds.

When it happens

Trigger: Setting POLARS_HTTP_CONNECT_TIMEOUT_SECONDS to '5min', '300.0', '0', '', or any non-NonZeroU64 string before scanning/writing to a cloud URL.

Common situations: Duration suffixes carried over from reqwest/HTTP-client style configs; zero intended as 'no timeout' (not supported — must be a positive integer); values generated by tools that quote env values.

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.

Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

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

Appendix: source

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

pub static USER_AGENT: &str = concat!("polars", "/", env!("CARGO_PKG_VERSION"),);

#[cfg(any(feature = "aws", feature = "gcp", feature = "azure", feature = "http"))]
pub(super) fn get_client_options() -> ClientOptions {
    use std::num::NonZeroU64;

    use reqwest::header::HeaderValue;

    ClientOptions::new()
        // Disables the time limit for downloading the response body.
        .with_timeout_disabled()
        // Set the time limit for establishing the connection.
        .with_connect_timeout(std::time::Duration::from_secs(
            std::env::var("POLARS_HTTP_CONNECT_TIMEOUT_SECONDS")
                .map(|x| {
                    x.parse::<NonZeroU64>()
                        .ok()
                        .unwrap_or_else(|| {
                            panic!("invalid value for POLARS_HTTP_CONNECT_TIMEOUT_SECONDS: {x}")
                        })
                        .get()
                })
                .unwrap_or(5 * 60),
        ))
        .with_user_agent(HeaderValue::from_static(USER_AGENT))
        .with_allow_http(true)
        .with_dns_resolver(Arc::new(
            CachingResolver::new(DnsResolverConfig::from_env()),
        ))
}

#[cfg(feature = "aws")]
fn read_config(
    builder: &mut AmazonS3Builder,
    items: &[(&Path, &[(&str, AmazonS3ConfigKey)])],
) -> Option<()> {
    use crate::path_utils::resolve_homedir;

View on GitHub (pinned to fe841f959e)