immich-app/immich · error · RuntimeError

Attempted to clear cache, but rmtree is not safe on this pla

Error message

Attempted to clear cache, but rmtree is not safe on this platform

What it means

Raised as RuntimeError by InferenceModel.clear_cache (models/base.py) when the cache directory exists but shutil.rmtree's rmtree.avoids_symlink_attacks is False on the current platform — i.e. the OS cannot guarantee rmtree is safe against symlink attacks, so Immich refuses to delete to avoid a potential security issue.

Source

Thrown at machine-learning/immich_ml/models/base.py:92

        snapshot_download(
            f"immich-app/{clean_name(self.model_name)}",
            cache_dir=self.cache_dir,
            local_dir=self.cache_dir,
            ignore_patterns=ignored_patterns.get(self.model_format, []),
        )

    def _load(self) -> ModelSession:
        return self._make_session(self.model_path)

    def clear_cache(self) -> None:
        if not self.cache_dir.exists():
            log.warning(
                f"Attempted to clear cache for model '{self.model_name}', but cache directory does not exist",
            )
            return
        if not rmtree.avoids_symlink_attacks:
            raise RuntimeError("Attempted to clear cache, but rmtree is not safe on this platform")

        if self.cache_dir.is_dir():
            log.info(f"Cleared cache directory for model '{self.model_name}'.")
            rmtree(self.cache_dir)
        else:
            log.warning(
                (
                    f"Encountered file instead of directory at cache path "
                    f"for '{self.model_name}'. Removing file and replacing with a directory."
                ),
            )
            self.cache_dir.unlink()
        self.cache_dir.mkdir(parents=True, exist_ok=True)

    def _make_session(self, model_path: Path) -> ModelSession:
        if not model_path.is_file():
            raise FileNotFoundError(f"Model file not found: {model_path}")

View on GitHub (pinned to 199723261c)

Solutions

Run the ML container on a mainstream Linux filesystem/Python where rmtree.avoids_symlink_attacks is True (the default on modern CPython).
Manually delete the cache directory from the host (docker exec / volume) instead of relying on clear_cache, then restart the service.
Upgrade the Python/OS so the symlink-safety flag is set.

Example fix

# before — calling clear_cache on an unsafe platform
model.clear_cache()  # raises RuntimeError

# after — remove cache out-of-band, then reload
# docker exec immich-machine-learning rm -rf /cache/<model>
# then restart the container / let the model re-download

Defensive patterns

Strategy: fallback

Validate before calling

import shutil
from pathlib import Path
def safe_clear_cache(cache_dir: Path) -> None:
    if not cache_dir.exists(): return
    if not shutil.rmtree.avoids_symlink_attacks:
        raise RuntimeError('rmtree unsafe on this platform')
    shutil.rmtree(cache_dir)

Type guard

def rmtree_is_safe() -> bool:
    import shutil
    return bool(getattr(shutil.rmtree, 'avoids_symlink_attacks', False))

Try / catch

try:
    model.clear_cache()
except RuntimeError as e:
    if 'not safe on this platform' in str(e):
        # remove out-of-band, then reload
        import subprocess; subprocess.run(['rm', '-rf', str(model.cache_dir)])
    else: raise

Prevention

Run the ML container on a mainstream Linux + modern Python where rmtree.avoids_symlink_attacks is True.
Manage the cache volume from the host rather than relying on clear_cache on edge platforms.

When it happens

Trigger: clear_cache is invoked (e.g. during model reload/cache invalidation) on a platform where shutil does not advertise symlink-attack-safe rmtree (historically some non-Windows setups, or older Python versions where the flag is not set).

Common situations: Running the ML service on an unusual filesystem or an older Python build where rmtree.avoids_symlink_attacks evaluates False; a hardened/sandboxed environment that strips the symlink guarantee; manually triggering cache clear on an unsupported platform.

Related errors

AI-assisted analysis of immich-app/immich@199723261c (2026-08-12). Data as JSON: /api/errors/51d3066a05609669. Report an issue: GitHub.