pola-rs/polars · error · std::io::Error

error initializing temporary directory

Error message

error initializing temporary directory: {e} consider explicitly setting POLARS_TEMP_DIR

What it means

This io::Error wraps any failure that occurs while Polars initializes its temporary directory (e.g. directory creation or path probing failed). The message suggests setting POLARS_TEMP_DIR explicitly because the default temporary-directory location may be unusable. The original error kind is preserved.

Solutions

Set POLARS_TEMP_DIR to a writable directory path before running the process.
Check/fix TMPDIR (or OS temp conventions) so the default temp path is writable.
Ensure the process user has write permission on the temp directory's parent.
Read the inner e.kind()/cause to identify the specific OS failure (PermissionDenied vs NotFound).

Example fix

// before
$ cargo run  # fails: default temp dir not writable
// after
$ POLARS_TEMP_DIR=/data/mytmp cargo run

Defensive patterns

Strategy: validation

Validate before calling

let tmp = std::env::var("POLARS_TEMP_DIR")
    .or_else(|_| std::env::var("TMPDIR"))
    .unwrap_or_else(|_| "/tmp".to_string());
assert!(std::path::Path::new(&tmp).is_dir(), "temp dir missing: {tmp}");
assert!(std::fs::metadata(&tmp)?.permissions().readonly() == false);

Try / catch

match std::io::Result::Err(e) {
    e if e.kind() == std::io::ErrorKind::PermissionDenied => {
        std::env::set_var("POLARS_TEMP_DIR", "/data/writable-tmp");
        // retry the operation
    }
    _ => return Err(e),
}

Prevention

Set POLARS_TEMP_DIR explicitly in container/CI/cloud environments
Verify the process user can create directories in the temp location at startup
Log TMPDIR/POLARS_TEMP_DIR values during deployment health checks

When it happens

Trigger: Any path that triggers temporary-directory initialization in polars-io path_utils when the chosen temp location cannot be created or resolved: permission-denied mkdir, read-only filesystem, missing parent directory, invalid path.

Common situations: Running in sandboxed/air-gapped environments where TMPDIR is unset or points somewhere non-writable; containers running as non-root; cloud workers with restricted /tmp; users with a broken TMPDIR env var.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

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

Appendix: source

Thrown at crates/polars-io/src/path_utils/mod.rs:80

            // Setting permissions on Windows is not as easy compared to Unix, but fortunately
            // the default temporary directory location is underneath the user profile, so we
            // shouldn't need to do anything.
            std::env::temp_dir().join("polars/")
        } else {
            std::env::temp_dir().join("polars/")
        }
        .into_boxed_path();

        let perm_result = create_dir_owner_only(path.as_ref());

        if std::env::var("POLARS_ALLOW_UNSECURED_TEMP_DIR").as_deref() != Ok("1") {
            perm_result?;
        }

        std::io::Result::Ok(path)
    })()
    .map_err(|e| {
        std::io::Error::new(
            e.kind(),
            format!(
                "error initializing temporary directory: {e} \
                 consider explicitly setting POLARS_TEMP_DIR"
            ),
        )
    })
    .unwrap()
});

/// Create a directory (and parents) with owner-only permissions (0o700) on Unix.
pub fn create_dir_owner_only(path: &Path) -> std::io::Result<()> {
    std::fs::create_dir_all(path)?;

    #[cfg(target_family = "unix")]
    {
        use std::os::unix::fs::PermissionsExt;

View on GitHub (pinned to fe841f959e)