{"record":{"id":"de32b16c55b22713","repo":"jax-ml/jax","slug":"error-reading-persistent-compilation-cache-entry-f-de32b1","errorCode":null,"errorMessage":"Error reading persistent compilation cache entry for '{module_name}': {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":819,"sourceCode":"    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:\n    if _should_raise_persistent_cache_error(ex):\n      raise\n    warnings.warn(\n        f\"Error reading persistent compilation cache entry for \"\n        f\"'{module_name}': {type(ex).__name__}: {ex}\")\n    return None, None\n\n\ndef _cache_write(cache_key: str,\n                 compile_time_secs: float,\n                 module_name: str,\n                 backend: xc.Client,\n                 executable: xc.LoadedExecutable) -> None:\n  \"\"\"Writes the `serialized_computation` and its compilation time to the\n  persistent compilation cache repository.\n  \"\"\"\n  # Only write cache entries from the first process. Otherwise we create\n  # problems with contention for writes on some filesystems, e.g., GCS.\n  log_priority = (logging.WARNING\n                  if config.explain_cache_misses.value\n                  and compilation_cache.is_persistent_cache_enabled()","sourceCodeStart":801,"sourceCodeEnd":837,"githubUrl":"https://github.com/jax-ml/jax/blob/1e1c6a8fc06dfcd1247076ec5cae4640cea5d7bb/jax/_src/compiler.py#L801-L837","documentation":"JAX tried to read a compiled executable from the persistent compilation cache during compile_or_get_cached, but the read or deserialization failed. It warns and returns (None, None), causing JAX to recompile the function instead of using the cached artifact.","triggerScenarios":"jit-compiled function executed with persistent compilation cache enabled; compilation_cache.get_executable_and_time raises — corrupt entry, unpicklable/unreadable storage, backend mismatch, or API/permission errors from the cache backend (GCS, S3, local FS issues).","commonSituations":"Shared cache bucket written by heterogeneous JAX/XLA versions; local cache dir deleted mid-run; read-only mount; stale OAuth token for cloud storage cache.","solutions":["Confirm the cache location exists and is readable/writable by the process.","Delete corrupt cache entries or the whole cache dir and let it repopulate.","Align JAX versions across machines sharing the cache.","Enable jax_raise_persistent_cache_errors to surface the underlying exception if you need to diagnose it."],"exampleFix":"# before\njax.config.update('jax_compilation_cache_dir', 'gs://shared/cache')  # read errors\n# after\njax.config.update('jax_compilation_cache_dir', '/local/nvme/jax-cache')\n# optional: raise instead of warn\njax.config.update('jax_raise_persistent_cache_errors', True)","handlingStrategy":"fallback","validationCode":"from jax._src.compilation_cache import compilation_cache\n# probe: compile a trivial fn and confirm cache round-trips\nimport jax\njax.config.update('jax_compilation_cache_dir', CACHE_DIR)\njax.jit(lambda x: x + 1)(1.0)  # if this warns, reads/writes are broken","typeGuard":null,"tryCatchPattern":"with warnings.catch_warnings(record=True) as caught:\n    warnings.simplefilter('always')\n    out = jitted_fn(*args)\nif any('reading persistent compilation cache' in str(c.message) for c in caught):\n    logging.warning('cache miss due to read failure; expect recompile')","preventionTips":["Keep cache dirs per JAX version (e.g. include version in path).","Set JAX_RAISE_PERSISTENT_CACHE_ERRORS=true in staging to catch store problems early."],"tags":["jax","compilation-cache","deserialization","io"],"backgroundTag":"cache-read-failure","analyzedSha":"1e1c6a8fc06dfcd1247076ec5cae4640cea5d7bb","analyzedAt":"2026-08-27T09:53:25.647Z","schemaVersion":2},"datasetVersion":"2026-08-27T13:17:12.746Z"}