Error reading persistent compilation cache entry for '{modul

Error message

Error reading persistent compilation cache entry for '{module_name}': {type(ex).__name__}: {ex}

What it means

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.

Source

Thrown at jax/_src/compiler.py:819

    return False


def _cache_read(
    module_name: str, cache_key: str, compile_options: xc.CompileOptions,
    backend: xc.Client, executable_devices: xc.DeviceList,
    host_callbacks: Sequence[Any],
) -> tuple[xc.LoadedExecutable | None, int | None]:
  """Looks up the `computation` and it's compilation time in the persistent
  compilation cache repository.
  """
  try:
    return compilation_cache.get_executable_and_time(
        cache_key, compile_options, backend, executable_devices,
        host_callbacks)
  except Exception as ex:
    if _should_raise_persistent_cache_error(ex):
      raise
    warnings.warn(
        f"Error reading persistent compilation cache entry for "
        f"'{module_name}': {type(ex).__name__}: {ex}")
    return None, None


def _cache_write(cache_key: str,
                 compile_time_secs: float,
                 module_name: str,
                 backend: xc.Client,
                 executable: xc.LoadedExecutable) -> None:
  """Writes the `serialized_computation` and its compilation time to the
  persistent compilation cache repository.
  """
  # Only write cache entries from the first process. Otherwise we create
  # problems with contention for writes on some filesystems, e.g., GCS.
  log_priority = (logging.WARNING
                  if config.explain_cache_misses.value
                  and compilation_cache.is_persistent_cache_enabled()

View on GitHub (pinned to 1e1c6a8fc0)

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.

Example fix

# before
jax.config.update('jax_compilation_cache_dir', 'gs://shared/cache')  # read errors
# after
jax.config.update('jax_compilation_cache_dir', '/local/nvme/jax-cache')
# optional: raise instead of warn
jax.config.update('jax_raise_persistent_cache_errors', True)

Defensive patterns

Strategy: fallback

Validate before calling

from jax._src.compilation_cache import compilation_cache
# probe: compile a trivial fn and confirm cache round-trips
import jax
jax.config.update('jax_compilation_cache_dir', CACHE_DIR)
jax.jit(lambda x: x + 1)(1.0)  # if this warns, reads/writes are broken

Try / catch

with warnings.catch_warnings(record=True) as caught:
    warnings.simplefilter('always')
    out = jitted_fn(*args)
if any('reading persistent compilation cache' in str(c.message) for c in caught):
    logging.warning('cache miss due to read failure; expect recompile')

Prevention

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.

When it happens

Trigger: 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).

Common situations: 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.

Related errors

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