{"record":{"id":"6f15d8cfaac06135","repo":"pola-rs/polars","slug":"failed-to-create-file-cache-metadata-directory-path-err","errorCode":null,"errorMessage":"failed to create file cache metadata directory: path = {}, err = {}","messagePattern":"failed to create file cache metadata directory: path = (.+?), err = (.+?)","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"crates/polars-io/src/file_cache/cache.rs","lineNumber":27,"sourceCode":"use super::entry::{DATA_PREFIX, FileCacheEntry, METADATA_PREFIX};\nuse super::eviction::EvictionManager;\nuse super::file_fetcher::FileFetcher;\nuse super::utils::FILE_CACHE_PREFIX;\nuse crate::path_utils::ensure_directory_init;\n\npub static FILE_CACHE: LazyLock<FileCache> = LazyLock::new(|| {\n    let prefix = FILE_CACHE_PREFIX.clone();\n\n    if config::verbose() {\n        eprintln!(\"file cache prefix: {}\", prefix);\n    }\n\n    let min_ttl = Arc::new(AtomicU64::from(get_env_file_cache_ttl()));\n    let notify_ttl_updated = Arc::new(tokio::sync::Notify::new());\n\n    let metadata_dir = prefix.join(std::str::from_utf8(&[METADATA_PREFIX]).unwrap());\n    if let Err(err) = ensure_directory_init(metadata_dir.as_std_path()) {\n        panic!(\n            \"failed to create file cache metadata directory: path = {}, err = {}\",\n            metadata_dir, err\n        )\n    }\n\n    let data_dir = prefix.join(std::str::from_utf8(&[DATA_PREFIX]).unwrap());\n\n    if let Err(err) = ensure_directory_init(data_dir.as_std_path()) {\n        panic!(\n            \"failed to create file cache data directory: path = {}, err = {}\",\n            data_dir, err\n        )\n    }\n\n    Box::leak(Box::new(EvictionManager {\n        data_dir,\n        metadata_dir,\n        files_to_remove: None,","sourceCodeStart":9,"sourceCodeEnd":45,"githubUrl":"https://github.com/pola-rs/polars/blob/fe841f959ef4d2ceefc05a310d33ed7b1ab24e5e/crates/polars-io/src/file_cache/cache.rs#L9-L45","documentation":"The file cache initializer creates a metadata directory under the cache prefix and panics if ensure_directory_init fails. This typically means a filesystem permission problem or invalid path. Since it runs in a LazyLock static, the panic fires on first use of the cloud file cache.","triggerScenarios":"First use of a cloud-based scan/read (CloudOptions path) that initializes FileCache; mkdir of <prefix>/<METADATA_PREFIX> fails due to permissions, read-only fs, or a file already existing at that path.","commonSituations":"POLARS_TEMP_DIR (or default temp dir) pointing at a read-only or noexec mount, sandboxed containers, or disk-full conditions.","solutions":["Ensure the temp/cache base directory is writable by the process user","Check the POLARS_TEMP_DIR environment variable points to a valid writable location","Free disk space if the filesystem is full","Fix ownership/permissions (e.g. chmod/chown) on the cache parent directory"],"exampleFix":"// before\nPOLARS_TEMP_DIR=/readonly/mnt\n// after\nPOLARS_TEMP_DIR=/tmp/polars-cache","handlingStrategy":"validation","validationCode":"use std::fs;\nlet base = std::env::var(\"POLARS_TEMP_DIR\").unwrap_or_else(|_| std::env::temp_dir().display().to_string());\nfs::create_dir_all(&base).expect(\"cache base dir must be creatable/writable\");","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Pre-flight check writability of the temp dir at app startup","Set POLARS_TEMP_DIR explicitly in containers to a writable volume","Monitor disk space on the cache volume"],"tags":["filesystem","cache","permissions","panic"],"backgroundTag":"mkdir-permission-denied","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"}