{"record":{"id":"d62bb3ee83462cf5","repo":"pola-rs/polars","slug":"failed-to-open-create-global-file-cache-lockfile-err","errorCode":null,"errorMessage":"failed to open/create global file cache lockfile: {err}","messagePattern":"failed to open/create global file cache lockfile: (.+?)","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"crates/polars-io/src/file_cache/cache_lock.rs","lineNumber":20,"sourceCode":"use std::sync::{Arc, LazyLock};\nuse std::time::Duration;\n\nuse fs4::FileExt;\nuse parking_lot::{RwLock, RwLockReadGuard, RwLockWriteGuard};\nuse polars_core::runtime::ASYNC;\n\nuse super::utils::FILE_CACHE_PREFIX;\n\npub(super) static GLOBAL_FILE_CACHE_LOCK: LazyLock<GlobalLock> = LazyLock::new(|| {\n    let path = FILE_CACHE_PREFIX.join(\".process-lock\");\n\n    let file = std::fs::OpenOptions::new()\n        .write(true)\n        .create(true)\n        .truncate(false)\n        .open(path)\n        .map_err(|err| {\n            panic!(\"failed to open/create global file cache lockfile: {err}\");\n        })\n        .unwrap();\n\n    let at_bool = Arc::new(AtomicBool::new(false));\n    // Holding this access tracker prevents the background task from\n    // unlocking the lock.\n    let access_tracker = AccessTracker(at_bool.clone());\n    let notify_lock_acquired = Arc::new(tokio::sync::Notify::new());\n    let notify_lock_acquired_2 = notify_lock_acquired.clone();\n\n    ASYNC.spawn(async move {\n        let at_bool = std::mem::ManuallyDrop::new(at_bool);\n        let access_tracker = at_bool.as_ref();\n        let notify_lock_acquired = notify_lock_acquired_2;\n        let verbose = false;\n\n        loop {\n            if verbose {","sourceCodeStart":2,"sourceCodeEnd":38,"githubUrl":"https://github.com/pola-rs/polars/blob/fe841f959ef4d2ceefc05a310d33ed7b1ab24e5e/crates/polars-io/src/file_cache/cache_lock.rs#L2-L38","documentation":"The global file cache lockfile cannot be opened or created at the lock path, and the library panics instead of proceeding without the lock. The lockfile coordinates the background eviction manager. Failure almost always indicates filesystem permission or path issues.","triggerScenarios":"First initialization of the file cache lock: OpenOptions write+create on the lockfile path fails (EACCES, EROFS, ENOENT parent, etc.).","commonSituations":"Read-only temp directories, restrictive sandbox/SELinux policies, or a directory path owned by another user in multi-user environments.","solutions":["Verify the cache directory and its parent are writable by the current user","Point POLARS_TEMP_DIR to a writable location","Check for sandbox/seccomp/SELinux rules blocking file creation in the temp dir","Ensure a stale root-owned lockfile isn't blocking creation (fix ownership or remove it)"],"exampleFix":"// before\nPOLARS_TEMP_DIR=/var/lock (root-owned)\n// after\nPOLARS_TEMP_DIR=/home/user/.cache/polars","handlingStrategy":"validation","validationCode":"use std::fs;\nlet base = std::env::var(\"POLARS_TEMP_DIR\").unwrap_or_else(|_| std::env::temp_dir().display().to_string());\nlet lock_probe = format!(\"{base}/.polars-lock-probe\");\nmatch fs::OpenOptions::new().write(true).create(true).truncate(false).open(&lock_probe) {\n    Ok(_) => { let _ = fs::remove_file(&lock_probe); }\n    Err(e) => panic!(\"cannot create lockfiles in {base}: {e}\"),\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Verify temp dir allows file creation (not just listing) at startup","Check sandbox/SELinux policies permit writes there","Clean up stale root-owned lockfiles after privileged runs"],"tags":["filesystem","cache","lockfile","permissions","panic"],"backgroundTag":"file-open-failed","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"}