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

error initializing temporary directory: {e} consider explici

Error message

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

What it means

Produced when Polars cannot initialize its per-user temporary directory (POLARS_TEMP_DIR_BASE_PATH, resolved from POLARS_TEMP_DIR or temp_dir()/polars-<user>/). Initialization creates the directory with owner-only 0o700 permissions; it fails if the directory cannot be created, chmod'd, or verified, or if $USER/$HOME are both unset on Unix. Because the LazyLock ends in .unwrap(), first access panics rather than returning an error. Setting POLARS_ALLOW_UNSECURED_TEMP_DIR=1 skips the strict permission check.

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 df599052da)

Solutions

Set POLARS_TEMP_DIR to a writable directory you own: export POLARS_TEMP_DIR=/var/tmp/$USER/polars
Remove or fix the stale directory: rm -rf /tmp/polars-$(whoami) so create_dir_owner_only can recreate it with 0o700
Ensure $USER (or $HOME) is set in service/container environments
As a last resort set POLARS_ALLOW_UNSECURED_TEMP_DIR=1 to skip the permission check (weaker isolation)

Example fix

# before: container with no $USER and shared /tmp
docker run myimage ...

# after
docker run -e USER=1000 -e POLARS_TEMP_DIR=/tmp/polars-run myimage ...

Defensive patterns

Strategy: validation

Validate before calling

# Pre-flight check before running Polars work that needs a temp dir
BASE="${POLARS_TEMP_DIR:-$(dirname "$TMPDIR" 2>/dev/null || echo /tmp)/polars-$(id -un)}"
mkdir -p "$BASE" && chmod 700 "$BASE" && [ -w "$BASE" ] \
  || echo "temp dir unusable: set POLARS_TEMP_DIR" >&2

Prevention

Set POLARS_TEMP_DIR explicitly in containers, services, and cron jobs
Ensure $USER or $HOME is present in minimal environments
Never reuse a polars temp dir across UIDs; delete stale /tmp/polars-* on provisioning
Only set POLARS_ALLOW_UNSECURED_TEMP_DIR=1 when the host temp dir is already isolated

When it happens

Trigger: First use of the temp dir (file cache, downloading, spilling) when TMPDIR points to an unwritable location, /tmp/polars-<user> already exists with wrong ownership/permissions (permission mismatch), or $USER and $HOME are both absent so the path cannot be built.

Common situations: Docker/Kubernetes with read-only root filesystems or shared multi-user /tmp; cron/systemd services with sparse environments lacking USER/HOME; a leftover polars temp dir created by root then used by another user; NAS/FUSE mounts where chmod fails.

Related errors

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