{"record":{"id":"aa825ed8cae61840","repo":"pola-rs/polars","slug":"failed-to-create-file-cache-directory-path-err","errorCode":null,"errorMessage":"failed to create file cache directory: path = {}, err = {}","messagePattern":"failed to create file cache directory: path = (.+?), err = (.+?)","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"crates/polars-io/src/file_cache/utils.rs","lineNumber":17,"sourceCode":"use std::sync::{Arc, LazyLock};\nuse std::time::UNIX_EPOCH;\n\nuse polars_error::{PolarsError, PolarsResult};\nuse polars_utils::pl_path::{CloudScheme, PlRefPath};\n\nuse super::cache::{FILE_CACHE, get_env_file_cache_ttl};\nuse super::entry::FileCacheEntry;\nuse super::file_fetcher::{CloudFileFetcher, LocalFileFetcher};\nuse crate::cloud::{CloudLocation, CloudOptions, build_object_store, object_path_from_str};\nuse crate::path_utils::{POLARS_TEMP_DIR_BASE_PATH, ensure_directory_init};\n\npub static FILE_CACHE_PREFIX: LazyLock<PlRefPath> = LazyLock::new(|| {\n    let path = PlRefPath::try_from_path(&POLARS_TEMP_DIR_BASE_PATH.join(\"file-cache/\")).unwrap();\n\n    if let Err(err) = ensure_directory_init(path.as_ref()) {\n        panic!(\n            \"failed to create file cache directory: path = {}, err = {}\",\n            path, err\n        );\n    }\n\n    path\n});\n\npub(super) fn last_modified_u64(metadata: &std::fs::Metadata) -> u64 {\n    u64::try_from(\n        metadata\n            .modified()\n            .unwrap()\n            .duration_since(UNIX_EPOCH)\n            .unwrap()\n            .as_millis(),\n    )\n    .unwrap()","sourceCodeStart":1,"sourceCodeEnd":35,"githubUrl":"https://github.com/pola-rs/polars/blob/fe841f959ef4d2ceefc05a310d33ed7b1ab24e5e/crates/polars-io/src/file_cache/utils.rs#L1-L35","documentation":"The FILE_CACHE_PREFIX static creates <temp-base>/file-cache/ on first use and panics if the directory cannot be created. It is the root of the whole file cache, so failure is fatal for cloud caching. Common causes are permissions, read-only filesystems, or invalid base paths.","triggerScenarios":"Any cloud (CloudOptions) file operation triggering LazyLock init of FILE_CACHE_PREFIX; ensure_directory_init fails with EACCES/EROFS/ENAMETOOLONG/etc.","commonSituations":"Containers with read-only /tmp, POLARS_TEMP_DIR pointing to an unwritable or nonexistent parent, or running under a locked-down service account.","solutions":["Set POLARS_TEMP_DIR to a writable directory","Create/fix permissions on the temp base path","Free disk space if the volume is full","Verify the process user owns or can write to the target directory"],"exampleFix":"// before\nPOLARS_TEMP_DIR=/mnt/readonly\n// after\nPOLARS_TEMP_DIR=/tmp","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(format!(\"{base}/file-cache\")).expect(\"file-cache dir must be creatable\");","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Set POLARS_TEMP_DIR to a guaranteed-writable path in containers/jobs","Preflight create_dir_all on the cache root at startup","Ensure the base path exists and length limits (ENAMETOOLONG) are respected"],"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"}