pola-rs/polars · critical

failed to create file cache data directory: path =

Error message

failed to create file cache data directory: path = {}, err = {}

What it means

Like the metadata directory panic, this fires when creating the file cache's data directory fails. It is a deliberate panic because the cache cannot function without the directory. Runs once via LazyLock initialization when cloud file caching is first used.

Solutions

1. Make the cache base directory writable (check POLARS_TEMP_DIR)
2. Remove any non-directory file colliding with the data dir path
3. Ensure sufficient disk space
4. Run with a user that has write access to the temp directory

use std::fs;
let base = std::env::var("POLARS_TEMP_DIR").unwrap_or_else(|_| std::env::temp_dir().display().to_string());
let probe = format!("{base}/.polars-write-test");
fs::write(&probe, b"x").expect("cache dir not writable");
let _ = fs::remove_file(&probe);

When it happens

Trigger: First cloud read/write initializing FileCache; creating <prefix>/<DATA_PREFIX> fails due to permissions, read-only filesystem, path conflicts, or ENOSPC.

Common situations: Container images with read-only /tmp, restricted service accounts, or a stale non-directory file occupying the data dir path.

Understand the failure class

Background: mkdir permission denied (EACCES): failed to create directory errors explained — this error's family across 32 libraries.

Related errors

• failed to create file cache directory: path =
• failed to create file cache metadata directory: path =
• failed to open/create global file cache lockfile
• failed to create spill directory
• finish_open: could not acquire shared lock on data file at

AI-assisted analysis of pola-rs/polars@fe841f959e (2026-09-18). Data as JSON: /api/errors/b96245dd3a244057. Report an issue: GitHub.

Appendix: source

Thrown at crates/polars-io/src/file_cache/cache.rs:36

    if config::verbose() {
        eprintln!("file cache prefix: {}", prefix);
    }

    let min_ttl = Arc::new(AtomicU64::from(get_env_file_cache_ttl()));
    let notify_ttl_updated = Arc::new(tokio::sync::Notify::new());

    let metadata_dir = prefix.join(std::str::from_utf8(&[METADATA_PREFIX]).unwrap());
    if let Err(err) = ensure_directory_init(metadata_dir.as_std_path()) {
        panic!(
            "failed to create file cache metadata directory: path = {}, err = {}",
            metadata_dir, err
        )
    }

    let data_dir = prefix.join(std::str::from_utf8(&[DATA_PREFIX]).unwrap());

    if let Err(err) = ensure_directory_init(data_dir.as_std_path()) {
        panic!(
            "failed to create file cache data directory: path = {}, err = {}",
            data_dir, err
        )
    }

    Box::leak(Box::new(EvictionManager {
        data_dir,
        metadata_dir,
        files_to_remove: None,
        min_ttl: min_ttl.clone(),
        notify_ttl_updated: notify_ttl_updated.clone(),
    }))
    .run_in_background();

    // Safety: We have created the data and metadata directories.
    unsafe { FileCache::new_unchecked(prefix, min_ttl, notify_ttl_updated) }
});

View on GitHub (pinned to fe841f959e)