pola-rs/polars · critical

failed to create file cache directory: path =

Error message

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

What it means

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.

Solutions

1. Set POLARS_TEMP_DIR to a writable directory
2. Create/fix permissions on the temp base path
3. Free disk space if the volume is full
4. Verify the process user owns or can write to the target directory

Example fix

// before
POLARS_TEMP_DIR=/mnt/readonly
// after
POLARS_TEMP_DIR=/tmp

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(format!("{base}/file-cache")).expect("file-cache dir must be creatable");

When it happens

Trigger: Any cloud (CloudOptions) file operation triggering LazyLock init of FILE_CACHE_PREFIX; ensure_directory_init fails with EACCES/EROFS/ENAMETOOLONG/etc.

Common situations: Containers with read-only /tmp, POLARS_TEMP_DIR pointing to an unwritable or nonexistent parent, or running under a locked-down service account.

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 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/aa825ed8cae61840. Report an issue: GitHub.

Appendix: source

Thrown at crates/polars-io/src/file_cache/utils.rs:17

use std::sync::{Arc, LazyLock};
use std::time::UNIX_EPOCH;

use polars_error::{PolarsError, PolarsResult};
use polars_utils::pl_path::{CloudScheme, PlRefPath};

use super::cache::{FILE_CACHE, get_env_file_cache_ttl};
use super::entry::FileCacheEntry;
use super::file_fetcher::{CloudFileFetcher, LocalFileFetcher};
use crate::cloud::{CloudLocation, CloudOptions, build_object_store, object_path_from_str};
use crate::path_utils::{POLARS_TEMP_DIR_BASE_PATH, ensure_directory_init};

pub static FILE_CACHE_PREFIX: LazyLock<PlRefPath> = LazyLock::new(|| {
    let path = PlRefPath::try_from_path(&POLARS_TEMP_DIR_BASE_PATH.join("file-cache/")).unwrap();

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

    path
});

pub(super) fn last_modified_u64(metadata: &std::fs::Metadata) -> u64 {
    u64::try_from(
        metadata
            .modified()
            .unwrap()
            .duration_since(UNIX_EPOCH)
            .unwrap()
            .as_millis(),
    )
    .unwrap()

View on GitHub (pinned to fe841f959e)