{"record":{"id":"b9def59483564127","repo":"pola-rs/polars","slug":"invalid-polars-max-cached-metadata-scans-value","errorCode":null,"errorMessage":"invalid `POLARS_MAX_CACHED_METADATA_SCANS` value","messagePattern":"invalid `POLARS_MAX_CACHED_METADATA_SCANS` value","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/polars-plan/src/plans/conversion/dsl_to_ir/scans.rs","lineNumber":762,"sourceCode":"        Some(PrimitiveLogicalType::Integer(\n            IntegerType::UInt8 | IntegerType::UInt16 | IntegerType::UInt32 | IntegerType::UInt64\n        ))\n    ) || matches!(\n        primitive_type.converted_type,\n        Some(\n            PrimitiveConvertedType::Uint8\n                | PrimitiveConvertedType::Uint16\n                | PrimitiveConvertedType::Uint32\n                | PrimitiveConvertedType::Uint64\n        )\n    )\n}\n\npub fn max_metadata_scan_cached() -> usize {\n    static MAX_SCANS_METADATA_CACHED: LazyLock<usize> = LazyLock::new(|| {\n        let value = std::env::var(\"POLARS_MAX_CACHED_METADATA_SCANS\").map_or(8, |v| {\n            v.parse::<usize>()\n                .expect(\"invalid `POLARS_MAX_CACHED_METADATA_SCANS` value\")\n        });\n\n        if value == 0 {\n            return usize::MAX;\n        }\n\n        if polars_config::config().verbose() {\n            eprintln!(\"parquet max cached metadata scans: {value}\")\n        };\n\n        value\n    });\n    *MAX_SCANS_METADATA_CACHED\n}\n\n/// A file with at most this many record batches is counted exactly, a larger one\n/// has its row count extrapolated from this many.\n#[cfg(feature = \"ipc\")]","sourceCodeStart":744,"sourceCodeEnd":780,"githubUrl":"https://github.com/pola-rs/polars/blob/fe841f959ef4d2ceefc05a310d33ed7b1ab24e5e/crates/polars-plan/src/plans/conversion/dsl_to_ir/scans.rs#L744-L780","documentation":"Polars reads the environment variable POLARS_MAX_CACHED_METADATA_SCANS to cap how many scan sources keep cached metadata (default 8; 0 means unlimited). If the variable is set to something that does not parse as usize, `max_metadata_scan_cached` panics with this message.","triggerScenarios":"Setting POLARS_MAX_CACHED_METADATA_SCANS to a non-integer or negative value (e.g. \"many\", \"-1\", \"8.0\", \"\") and then executing any lazy query that performs file scans (infer_or_parse path).","commonSituations":"Typo in a deployment config / .env file, shell quoting leaving stray characters, or copying a docs example with a wrong value.","solutions":["Set POLARS_MAX_CACHED_METADATA_SCANS to a non-negative integer (e.g. 8) or unset it to use the default","Use 0 to disable the cap (unlimited cached metadata scans)","Check container/k8s env definitions for typos or whitespace in the value"],"exampleFix":"# before\nPOLARS_MAX_CACHED_METADATA_SCANS=8.0\n# after\nPOLARS_MAX_CACHED_METADATA_SCANS=8","handlingStrategy":"validation","validationCode":"import os\nv = os.environ.get(\"POLARS_MAX_CACHED_METADATA_SCANS\")\nif v is not None:\n    assert v.isdigit() or (v.startswith(\"-\") and False), f\"POLARS_MAX_CACHED_METADATA_SCANS must be a non-negative integer, got {v!r}\"","typeGuard":"def is_valid_scan_cache_value(v: str | None) -> bool:\n    return v is None or v.isdigit()","tryCatchPattern":null,"preventionTips":["Validate numeric env vars in deployment config before app start","Unset the variable to rely on the default (8)","Use 0 deliberately for unlimited caching"],"tags":["env-var","configuration","scan","panic"],"backgroundTag":"invalid-env-var-value","analyzedSha":"fe841f959ef4d2ceefc05a310d33ed7b1ab24e5e","analyzedAt":"2026-09-18T22:14:11.667Z","contentChangedAt":"2026-09-18T22:14:11.667Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}