{"record":{"id":"70d0d4985c7e25d8","repo":"jax-ml/jax","slug":"error-reading-persistent-compilation-cache-entry-f","errorCode":null,"errorMessage":"Error reading persistent compilation cache entry for '{cache_key}': {type(ex).__name__}: {ex}","messagePattern":"Error reading persistent compilation cache entry for '(.+?)': (.+?): (.+?)","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"jax/_src/compiler.py","lineNumber":798,"sourceCode":"\n\ndef _should_raise_persistent_cache_error(ex: Exception) -> bool:\n  \"\"\"Returns True if the exception should be raised, False if it should be warned.\"\"\"\n  return (\n      config.raise_persistent_cache_errors.value or\n      isinstance(ex, compilation_cache.CacheVerificationError)\n  )\n\n\ndef _is_executable_in_cache(backend, cache_key) -> bool:\n  \"\"\"Checks if executable is presented in cache on a given key\n  \"\"\"\n  try:\n    return compilation_cache.is_executable_in_cache(backend, cache_key)\n  except Exception as ex:\n    if _should_raise_persistent_cache_error(ex):\n      raise\n    warnings.warn(\n        f\"Error reading persistent compilation cache entry for \"\n        f\"'{cache_key}': {type(ex).__name__}: {ex}\")\n    return False\n\n\ndef _cache_read(\n    module_name: str, cache_key: str, compile_options: xc.CompileOptions,\n    backend: xc.Client, executable_devices: xc.DeviceList,\n    host_callbacks: Sequence[Any],\n) -> tuple[xc.LoadedExecutable | None, int | None]:\n  \"\"\"Looks up the `computation` and it's compilation time in the persistent\n  compilation cache repository.\n  \"\"\"\n  try:\n    return compilation_cache.get_executable_and_time(\n        cache_key, compile_options, backend, executable_devices,\n        host_callbacks)\n  except Exception as ex:","sourceCodeStart":780,"sourceCodeEnd":816,"githubUrl":"https://github.com/jax-ml/jax/blob/1e1c6a8fc06dfcd1247076ec5cae4640cea5d7bb/jax/_src/compiler.py#L780-L816","documentation":"JAX persisted a compiled executable in a persistent compilation cache (jax_compilation_cache). While checking whether an executable exists for a cache key, the cache read failed (e.g. corrupt entry, unreadable GCS/S3 bucket, deserialization mismatch). JAX downgrades this to a warning and recompiles from scratch.","triggerScenarios":"Calling any jitted function with JAX's persistent compilation cache enabled (jax.config.jax_compilation_cache_dir set, or JAX_COMPILATION_CACHE_DIR env var) when the cache store returns an error in compilation_cache.is_executable_in_cache: invalid credentials, missing bucket, corrupted cache files, or a version-incompatible pickle.","commonSituations":"CI jobs where the cache bucket credentials expired; cache written by an older JAX version and read by a newer one; cache directory on a network mount that's flaky; huge caches hitting GCS rate limits.","solutions":["Verify the cache directory/bucket is accessible and credentials are valid (e.g. gsutil ls on the cache dir).","Clear the stale cache directory (or point JAX_COMPILATION_CACHE_DIR to a fresh location) if entries are corrupt or from an incompatible version.","If a storage-layer error should fail loudly, set jax_raise_persistent_cache_errors=True (or JAX_RAISE_PERSISTENT_CACHE_ERRORS=true) and fix the underlying store error.","Update JAX on all writers/readers of the shared cache so serialization formats match."],"exampleFix":"# before\nexport JAX_COMPILATION_CACHE_DIR=gs://my-bucket/cache  # failing reads\n# after\nexport JAX_COMPILATION_CACHE_DIR=/tmp/fresh-jax-cache  # local, writable dir\n# or fail fast on cache errors:\njax.config.update('jax_raise_persistent_cache_errors', True)","handlingStrategy":"fallback","validationCode":"import os\nfrom pathlib import Path\ndef cache_dir_ok(d):\n    p = Path(d.replace('gs://','') if d.startswith('gs://') else d)\n    return os.access(p, os.R_OK) if p.exists() else False","typeGuard":null,"tryCatchPattern":"import warnings\nwith warnings.catch_warnings(record=True) as w:\n    warnings.simplefilter('always')\n    result = jitted_fn(x)  # falls back to recompilation on cache failure\nassert any('persistent compilation cache' in str(i.message) for i in w) or True","preventionTips":["Health-check the cache bucket/dir before long jobs.","Pin one JAX version across all writers of a shared cache.","Monitor for this warning in CI logs; it silently costs recompilation time."],"tags":["jax","compilation-cache","persistence","io"],"backgroundTag":"cache-read-failure","analyzedSha":"1e1c6a8fc06dfcd1247076ec5cae4640cea5d7bb","analyzedAt":"2026-08-27T09:53:25.647Z","schemaVersion":2},"datasetVersion":"2026-08-27T13:17:12.746Z"}