What causes "{ENV_CACHE_WARM_SAMPLE_PCT}: {error}" in xai-org/x-algorithm?

Set the variable to an integer between 0 and 100 (e.g. VF_CACHE_WARM_SAMPLE_PCT=10), or unset it entirely to default to 0.

xai-org/x-algorithm · error

{ENV_CACHE_WARM_SAMPLE_PCT}: {error}

Error message

{ENV_CACHE_WARM_SAMPLE_PCT}: {error}

What it means

The VF cache warm sampling percentage is read from the environment variable named by ENV_CACHE_WARM_SAMPLE_PCT and parsed by parse_sample_pct; a present-but-malformed value (not 0-100, non-numeric, negative) causes this panic with the variable name and the parse error. An unset or empty value safely defaults to 0.

Source

Thrown at visibility-filtering/config.rs:60

pub fn fallback_cache_serve_stale_enabled() -> bool {
    parse_env_flag(
        std::env::var(ENV_FALLBACK_CACHE_SERVE_STALE_ENABLED)
            .ok()
            .as_deref(),
    )
}

pub fn fallback_cache_populate_enabled() -> bool {
    parse_env_flag(
        std::env::var(ENV_FALLBACK_CACHE_POPULATE_ENABLED)
            .ok()
            .as_deref(),
    )
}

pub fn cache_warm_sample_pct() -> u8 {
    parse_sample_pct(std::env::var(ENV_CACHE_WARM_SAMPLE_PCT).ok().as_deref())
        .unwrap_or_else(|error| panic!("{ENV_CACHE_WARM_SAMPLE_PCT}: {error}"))
}

fn parse_sample_pct(value: Option<&str>) -> Result<u8, String> {
    let Some(value) = value.map(str::trim).filter(|v| !v.is_empty()) else {
        return Ok(0);
    };
    match value.parse::<u8>() {
        Ok(pct) if pct <= 100 => Ok(pct),
        _ => Err(format!("expected an integer 0-100, got {value:?}")),
    }
}

fn parse_env_flag(value: Option<&str>) -> bool {
    value.is_some_and(|value| {
        matches!(
            value.to_ascii_lowercase().as_str(),
            "1" | "true" | "yes" | "on"
        )

View on GitHub (pinned to 24c60942c5)

Solutions

Set the variable to an integer between 0 and 100 (e.g. VF_CACHE_WARM_SAMPLE_PCT=10), or unset it entirely to default to 0.
Check for stray whitespace/quotes/% signs in the env var value in your deployment manifest.
If you control the crate, replace the panic with a logged warning and fallback to 0 for resilience.

Example fix

// before
pub fn cache_warm_sample_pct() -> u8 {
    parse_sample_pct(std::env::var(ENV_CACHE_WARM_SAMPLE_PCT).ok().as_deref())
        .unwrap_or_else(|error| panic!("{ENV_CACHE_WARM_SAMPLE_PCT}: {error}"))
}

// after
pub fn cache_warm_sample_pct() -> u8 {
    parse_sample_pct(std::env::var(ENV_CACHE_WARM_SAMPLE_PCT).ok().as_deref())
        .unwrap_or_else(|error| {
            tracing::warn!("invalid {ENV_CACHE_WARM_SAMPLE_PCT}: {error}; defaulting to 0");
            0
        })
}

Defensive patterns

Strategy: validation

Validate before calling

fn valid_sample_pct() -> Result<u8, String> {
    match std::env::var("VF_CACHE_WARM_SAMPLE_PCT") {
        Ok(v) if v.trim().is_empty() => Ok(0),
        Ok(v) => v.trim().parse::<u8>().ok()
            .filter(|p| *p <= 100)
            .ok_or_else(|| format!("bad pct: {v}")),
        Err(_) => Ok(0),
    }
}
// run before calling cache_warm_sample_pct()

Type guard

fn is_valid_pct(s: &str) -> bool {
    s.trim().parse::<u8>().map(|v| v <= 100).unwrap_or(false)
}

Try / catch

let pct = std::panic::catch_unwind(cache_warm_sample_pct)
    .unwrap_or_else(|_| { log::warn!("invalid pct env; using 0"); 0 });

Prevention

Validate env vars in a startup config check that reports all problems at once.
Use integers 0-100 without '%' suffix; document allowed range next to the var name.
Prefer fail-fast config validation with clear messages over deep runtime panics.
Lint deployment manifests for numeric env var formatting.

When it happens

Trigger: Setting the cache warm sample pct env var to something like 'abc', '150', '-1', '1.5', or '50%' — any string parse_sample_pct rejects. Startup then panics inside cache_warm_sample_pct().

Common situations: Typos in deployment env files, percentage written with a '%' suffix, decimal values where u8 integer is expected, copying a value from another environment with different constraints.

Related errors

AI-assisted analysis of xai-org/x-algorithm@24c60942c5 (2026-08-28). Data as JSON: /api/errors/fc9623fa87001609. Report an issue: GitHub.