{"record":{"id":"5678fd24ee8fa95b","repo":"jax-ml/jax","slug":"please-install-the-etils-epath-package-to-speci","errorCode":null,"errorMessage":"Please install the `etils[epath]` package to specify a cache directory on a non-local filesystem","messagePattern":"Please install the `etils\\[epath\\]` package to specify a cache directory on a non-local filesystem","errorType":"error_code","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"jax/_src/lru_cache.py","lineNumber":64,"sourceCode":"  This implementation includes cache reading, writing and eviction\n  based on the LRU policy.\n\n  Notably, when ``max_size`` is set to -1, the cache eviction\n  is disabled, and the LRU cache functions as a normal cache\n  without any size limitations.\n  \"\"\"\n\n  def __init__(self, path: str, *, max_size: int, lock_timeout_secs: float | None = 10):\n    \"\"\"Args:\n\n      path: The path to the cache directory.\n      max_size: The maximum size of the cache in bytes. Caching will be\n        disabled if this value is set to ``0``. A special value of ``-1``\n        indicates no limit, allowing the cache size to grow indefinitely.\n      lock_timeout_secs: (optional) The timeout for acquiring a file lock.\n    \"\"\"\n    if not _is_local_filesystem(path) and not pathlib.epath_installed:\n      raise RuntimeError(\"Please install the `etils[epath]` package to specify a cache directory on a non-local filesystem\")\n\n    self.path = self._path = pathlib.Path(path)\n    self.path.mkdir(parents=True, exist_ok=True)\n\n    self.eviction_enabled = max_size != -1  # no eviction if `max_size` is set to -1\n\n    if self.eviction_enabled:\n      if filelock is None:\n        raise RuntimeError(\"Please install the `filelock` package to set `jax_compilation_cache_max_size`\")\n\n      self.max_size = max_size\n      self.lock_timeout_secs = lock_timeout_secs\n\n      self.lock_path = self.path / \".lockfile\"\n      if _is_local_filesystem(path):\n        self.lock = filelock.FileLock(self.lock_path)\n      else:\n        self.lock = filelock.SoftFileLock(self.lock_path)","sourceCodeStart":46,"sourceCodeEnd":82,"githubUrl":"https://github.com/jax-ml/jax/blob/1e1c6a8fc06dfcd1247076ec5cae4640cea5d7bb/jax/_src/lru_cache.py#L46-L82","documentation":"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.","triggerScenarios":"Setting jax_compilation_cache_dir to a gs:// or s3:// path without having installed 'etils[epath]'.","commonSituations":"Enabling the persistent compilation cache on Cloud Storage for TPU/cloud training jobs; CI environments with a minimal JAX install missing the etils extra.","solutions":["pip install 'etils[epath]'","Or point jax_compilation_cache_dir at a local filesystem path","Verify the path scheme — a typo like 'gss://' makes even a valid setup look non-local"],"exampleFix":"# before\njax.config.update('jax_compilation_cache_dir', 'gs://my-bucket/cache')\n\n# after\n# pip install 'etils[epath]'\njax.config.update('jax_compilation_cache_dir', 'gs://my-bucket/cache')","handlingStrategy":"validation","validationCode":"import urllib.parse\nscheme = urllib.parse.urlparse(cache_dir).scheme\nneeds_epath = scheme not in ('', 'file')\nif needs_epath:\n    import importlib.util; assert importlib.util.find_spec('etils.epath')","typeGuard":null,"tryCatchPattern":"try:\n    jax.config.update('jax_compilation_cache_dir', cache_dir)\nexcept RuntimeError:\n    jax.config.update('jax_compilation_cache_dir', '/tmp/jax_cache')  # local fallback","preventionTips":["Add 'etils[epath]' to requirements when using cloud cache dirs","Smoke-test cache setup at process start"],"tags":["jax","compilation-cache","optional-dependency","cloud-storage"],"backgroundTag":"missing-optional-dependency","analyzedSha":"1e1c6a8fc06dfcd1247076ec5cae4640cea5d7bb","analyzedAt":"2026-08-27T09:53:25.647Z","schemaVersion":2},"datasetVersion":"2026-08-27T13:17:12.746Z"}