pola-rs/polars · critical

failed to create file cache metadata directory: path =

Error message

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

What it means

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.

Solutions

1. Ensure the temp/cache base directory is writable by the process user
2. Check the POLARS_TEMP_DIR environment variable points to a valid writable location
3. Free disk space if the filesystem is full
4. Fix ownership/permissions (e.g. chmod/chown) on the cache parent directory

Example fix

// before
POLARS_TEMP_DIR=/readonly/mnt
// after
POLARS_TEMP_DIR=/tmp/polars-cache

use std::fs;
let base = std::env::var("POLARS_TEMP_DIR").unwrap_or_else(|_| std::env::temp_dir().display().to_string());
fs::create_dir_all(&base).expect("cache base dir must be creatable/writable");

When it happens

Trigger: 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.

Common situations: POLARS_TEMP_DIR (or default temp dir) pointing at a read-only or noexec mount, sandboxed containers, or disk-full conditions.

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 data directory: path =
• failed to create file cache 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/6f15d8cfaac06135. Report an issue: GitHub.

Appendix: source

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

use super::entry::{DATA_PREFIX, FileCacheEntry, METADATA_PREFIX};
use super::eviction::EvictionManager;
use super::file_fetcher::FileFetcher;
use super::utils::FILE_CACHE_PREFIX;
use crate::path_utils::ensure_directory_init;

pub static FILE_CACHE: LazyLock<FileCache> = LazyLock::new(|| {
    let prefix = FILE_CACHE_PREFIX.clone();

    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,

View on GitHub (pinned to fe841f959e)