{"record":{"id":"f884e651ae486359","repo":"pola-rs/polars","slug":"invalid-polars-pq-prefiltered-mask-value-v","errorCode":null,"errorMessage":"Invalid `POLARS_PQ_PREFILTERED_MASK` value '{v}'.","messagePattern":"Invalid `POLARS_PQ_PREFILTERED_MASK` value '(.+?)'\\.","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/polars-io/src/parquet/read/read_impl.rs","lineNumber":515,"sourceCode":"    // Closer to 0: pre-filtering is probably better.\n    // Closer to 1: post-filtering is probably better.\n    (num_edges / rg_len).clamp(0.0, 1.0)\n}\n\n#[derive(Clone, Copy)]\npub enum PrefilterMaskSetting {\n    Auto,\n    Pre,\n    Post,\n}\n\nimpl PrefilterMaskSetting {\n    pub fn init_from_env() -> Self {\n        std::env::var(\"POLARS_PQ_PREFILTERED_MASK\").map_or(Self::Auto, |v| match &v[..] {\n            \"auto\" => Self::Auto,\n            \"pre\" => Self::Pre,\n            \"post\" => Self::Post,\n            _ => panic!(\"Invalid `POLARS_PQ_PREFILTERED_MASK` value '{v}'.\"),\n        })\n    }\n\n    pub fn should_prefilter(&self, prefilter_cost: f64, dtype: &ArrowDataType) -> bool {\n        match self {\n            Self::Auto => {\n                // Prefiltering is only expensive for nested types so we make the cut-off quite\n                // high.\n                let is_nested = dtype.is_nested();\n\n                // We empirically selected these numbers.\n                !is_nested && prefilter_cost <= 0.01\n            },\n            Self::Pre => true,\n            Self::Post => false,\n        }\n    }\n}","sourceCodeStart":497,"sourceCodeEnd":533,"githubUrl":"https://github.com/pola-rs/polars/blob/fc24390824009e8fc5b7870e256273c1b140a019/crates/polars-io/src/parquet/read/read_impl.rs#L497-L533","documentation":"PrefilterMaskSetting::init_from_env() maps POLARS_PQ_PREFILTERED_MASK to the strategy for applying row-group masks during predicate pushdown in Parquet reads: exactly \"auto\" (cost heuristic, default), \"pre\" (push mask before decode) or \"post\". Any other string - including case variants like \"Pre\" - panics the first time the setting is initialized during a Parquet scan with a predicate.","triggerScenarios":"export POLARS_PQ_PREFILTERED_MASK=true|1|PRE|\"pre \" (any non-empty value other than auto/pre/post) followed by any lazy Parquet scan with a filter, e.g. LazyFrame::scan_parquet(path, args)?.filter(col(\"a\").gt(lit(1))).collect().","commonSituations":"Benchmark tuning copied from blog posts that assume boolean env flags; CI matrices exporting the variable for perf runs; trailing whitespace or quotes introduced by YAML/.env injection.","solutions":["Use one of the exact lowercase literals: export POLARS_PQ_PREFILTERED_MASK=pre (or auto|post)","Or unset the variable to fall back to the auto heuristic","Strip whitespace/quotes where the value is injected (CI secrets, Helm values, .env files)"],"exampleFix":"# before\nexport POLARS_PQ_PREFILTERED_MASK=1\n\n# after\nexport POLARS_PQ_PREFILTERED_MASK=pre\n# or: unset POLARS_PQ_PREFILTERED_MASK","handlingStrategy":"validation","validationCode":"fn validate_pq_env() -> Result<(), String> {\n    if let Ok(v) = std::env::var(\"POLARS_PQ_PREFILTERED_MASK\") {\n        if !matches!(v.as_str(), \"auto\" | \"pre\" | \"post\") {\n            return Err(format!(\n                \"POLARS_PQ_PREFILTERED_MASK must be one of auto|pre|post, got {v:?}\"\n            ));\n        }\n    }\n    Ok(())\n}","typeGuard":null,"tryCatchPattern":"Deterministic env panic at first predicate scan; catch_unwind adds only a nicer message. Fix or unset the variable.","preventionTips":["Validate every enum-valued POLARS_* knob against its literal set at startup","Trim whitespace/quotes where CI injects env values","Keep a curated list of sanctioned polars env vars in deployment docs"],"tags":["polars","parquet","environment-variable","predicate-pushdown","panic","configuration"],"backgroundTag":"invalid-env-var-value","analyzedSha":"fc24390824009e8fc5b7870e256273c1b140a019","analyzedAt":"2026-08-19T12:15:06.350Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}