{"record":{"id":"fe60ae8abb09568e","repo":"pola-rs/polars","slug":"error-initializing-temporary-directory-e-consid","errorCode":null,"errorMessage":"error initializing temporary directory: {e} consider explicitly setting POLARS_TEMP_DIR","messagePattern":"error initializing temporary directory: (.+?) consider explicitly setting POLARS_TEMP_DIR","errorType":"panic","errorClass":"std::io::Error","httpStatus":null,"severity":"critical","filePath":"crates/polars-io/src/path_utils/mod.rs","lineNumber":80,"sourceCode":"            // Setting permissions on Windows is not as easy compared to Unix, but fortunately\n            // the default temporary directory location is underneath the user profile, so we\n            // shouldn't need to do anything.\n            std::env::temp_dir().join(\"polars/\")\n        } else {\n            std::env::temp_dir().join(\"polars/\")\n        }\n        .into_boxed_path();\n\n        let perm_result = create_dir_owner_only(path.as_ref());\n\n        if std::env::var(\"POLARS_ALLOW_UNSECURED_TEMP_DIR\").as_deref() != Ok(\"1\") {\n            perm_result?;\n        }\n\n        std::io::Result::Ok(path)\n    })()\n    .map_err(|e| {\n        std::io::Error::new(\n            e.kind(),\n            format!(\n                \"error initializing temporary directory: {e} \\\n                 consider explicitly setting POLARS_TEMP_DIR\"\n            ),\n        )\n    })\n    .unwrap()\n});\n\n/// Create a directory (and parents) with owner-only permissions (0o700) on Unix.\npub fn create_dir_owner_only(path: &Path) -> std::io::Result<()> {\n    std::fs::create_dir_all(path)?;\n\n    #[cfg(target_family = \"unix\")]\n    {\n        use std::os::unix::fs::PermissionsExt;\n","sourceCodeStart":62,"sourceCodeEnd":98,"githubUrl":"https://github.com/pola-rs/polars/blob/df599052daf96e7a9cc30a3b0c6bd25d6947e3c0/crates/polars-io/src/path_utils/mod.rs#L62-L98","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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)"],"exampleFix":"# before: container with no $USER and shared /tmp\ndocker run myimage ...\n\n# after\ndocker run -e USER=1000 -e POLARS_TEMP_DIR=/tmp/polars-run myimage ...","handlingStrategy":"validation","validationCode":"# Pre-flight check before running Polars work that needs a temp dir\nBASE=\"${POLARS_TEMP_DIR:-$(dirname \"$TMPDIR\" 2>/dev/null || echo /tmp)/polars-$(id -un)}\"\nmkdir -p \"$BASE\" && chmod 700 \"$BASE\" && [ -w \"$BASE\" ] \\\n  || echo \"temp dir unusable: set POLARS_TEMP_DIR\" >&2","typeGuard":null,"tryCatchPattern":null,"preventionTips":["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"],"tags":["rust","polars","environment","temp-dir","permissions","panic"],"backgroundTag":null,"analyzedSha":"df599052daf96e7a9cc30a3b0c6bd25d6947e3c0","analyzedAt":"2026-08-16T12:10:03.978Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}