jax-ml/jax · error · RuntimeError

Please install the `etils[epath]` package to specify a cache

Error message

Please install the `etils[epath]` package to specify a cache directory on a non-local filesystem

What it means

LRUCache (used for the JAX persistent compilation cache) supports non-local filesystems (GCS, S3, etc.) only through etils' epath abstraction. If the cache path is on a non-local filesystem and etils[epath] is not installed, __init__ raises RuntimeError immediately.

Source

Thrown at jax/_src/lru_cache.py:64

  This implementation includes cache reading, writing and eviction
  based on the LRU policy.

  Notably, when ``max_size`` is set to -1, the cache eviction
  is disabled, and the LRU cache functions as a normal cache
  without any size limitations.
  """

  def __init__(self, path: str, *, max_size: int, lock_timeout_secs: float | None = 10):
    """Args:

      path: The path to the cache directory.
      max_size: The maximum size of the cache in bytes. Caching will be
        disabled if this value is set to ``0``. A special value of ``-1``
        indicates no limit, allowing the cache size to grow indefinitely.
      lock_timeout_secs: (optional) The timeout for acquiring a file lock.
    """
    if not _is_local_filesystem(path) and not pathlib.epath_installed:
      raise RuntimeError("Please install the `etils[epath]` package to specify a cache directory on a non-local filesystem")

    self.path = self._path = pathlib.Path(path)
    self.path.mkdir(parents=True, exist_ok=True)

    self.eviction_enabled = max_size != -1  # no eviction if `max_size` is set to -1

    if self.eviction_enabled:
      if filelock is None:
        raise RuntimeError("Please install the `filelock` package to set `jax_compilation_cache_max_size`")

      self.max_size = max_size
      self.lock_timeout_secs = lock_timeout_secs

      self.lock_path = self.path / ".lockfile"
      if _is_local_filesystem(path):
        self.lock = filelock.FileLock(self.lock_path)
      else:
        self.lock = filelock.SoftFileLock(self.lock_path)

View on GitHub (pinned to 1e1c6a8fc0)

Solutions

1. pip install 'etils[epath]'
2. Or point jax_compilation_cache_dir at a local filesystem path
3. Verify the path scheme — a typo like 'gss://' makes even a valid setup look non-local

Example fix

# before
jax.config.update('jax_compilation_cache_dir', 'gs://my-bucket/cache')

# after
# pip install 'etils[epath]'
jax.config.update('jax_compilation_cache_dir', 'gs://my-bucket/cache')

import urllib.parse
scheme = urllib.parse.urlparse(cache_dir).scheme
needs_epath = scheme not in ('', 'file')
if needs_epath:
    import importlib.util; assert importlib.util.find_spec('etils.epath')

try:
    jax.config.update('jax_compilation_cache_dir', cache_dir)
except RuntimeError:
    jax.config.update('jax_compilation_cache_dir', '/tmp/jax_cache')  # local fallback

When it happens

Trigger: Setting jax_compilation_cache_dir to a gs:// or s3:// path without having installed 'etils[epath]'.

Common situations: Enabling the persistent compilation cache on Cloud Storage for TPU/cloud training jobs; CI environments with a minimal JAX install missing the etils extra.

Related errors

• Please install the `filelock` package to set `jax_compilatio
• Error reading persistent compilation cache entry for '{cache
• Error reading persistent compilation cache entry for '{modul
• Error writing persistent compilation cache entry for '{modul
• numpy masked arrays are not supported as direct inputs to JA

AI-assisted analysis of jax-ml/jax@1e1c6a8fc0 (2026-08-27). Data as JSON: /api/errors/5678fd24ee8fa95b. Report an issue: GitHub.