{"record":{"id":"25548a0d78699dc5","repo":"jax-ml/jax","slug":"please-install-the-filelock-package-to-set-jax","errorCode":null,"errorMessage":"Please install the `filelock` package to set `jax_compilation_cache_max_size`","messagePattern":"Please install the `filelock` package to set `jax_compilation_cache_max_size`","errorType":"error_code","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"jax/_src/lru_cache.py","lineNumber":73,"sourceCode":"    \"\"\"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)\n\n  def get(self, key: str) -> bytes | None:\n    \"\"\"Retrieves the cached value for the given key.\n\n    Args:\n      key: The key for which the cache value is retrieved.\n\n    Returns:\n      The cached data as bytes if available; ``None`` otherwise.","sourceCodeStart":55,"sourceCodeEnd":91,"githubUrl":"https://github.com/jax-ml/jax/blob/1e1c6a8fc06dfcd1247076ec5cae4640cea5d7bb/jax/_src/lru_cache.py#L55-L91","documentation":"Enabling cache eviction (any jax_compilation_cache_max_size other than -1) requires the filelock package for cross-process locking. If filelock is not installed, LRUCache.__init__ raises RuntimeError at setup time.","triggerScenarios":"Setting jax_compilation_cache_max_size to a positive byte value without filelock installed.","commonSituations":"Adding a cache size cap to prevent unbounded disk growth in long-running training jobs; slim docker images where jax extras were not installed.","solutions":["pip install filelock","Or set jax_compilation_cache_max_size to -1 (no eviction, no lock needed)","Or disable the compilation cache entirely"],"exampleFix":"# before\njax.config.update('jax_compilation_cache_max_size', 10 * 2**30)\n\n# after\n# pip install filelock\njax.config.update('jax_compilation_cache_max_size', 10 * 2**30)","handlingStrategy":"validation","validationCode":"import importlib.util\nif max_size not in (-1, 0):\n    assert importlib.util.find_spec('filelock'), 'pip install filelock'","typeGuard":null,"tryCatchPattern":"try:\n    jax.config.update('jax_compilation_cache_max_size', size)\nexcept RuntimeError:\n    jax.config.update('jax_compilation_cache_max_size', -1)","preventionTips":["Install filelock alongside any cache-size cap","Default max_size to -1 in configs where the extra may be missing"],"tags":["jax","compilation-cache","optional-dependency","filelock"],"backgroundTag":"missing-optional-dependency","analyzedSha":"1e1c6a8fc06dfcd1247076ec5cae4640cea5d7bb","analyzedAt":"2026-08-27T09:53:25.647Z","schemaVersion":2},"datasetVersion":"2026-08-27T13:17:12.746Z"}