Error writing persistent compilation cache entry for '{modul

Error message

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

What it means

After successfully compiling a function, JAX failed to write the executable into the persistent compilation cache (put_executable_and_time raised). The computation still runs; only cache persistence is lost, so future runs will recompile.

Source

Thrown at jax/_src/compiler.py:863

  if compile_time_secs < min_compile_time:
    logger.log(
        log_priority,
        "Not writing persistent cache entry for '%s' because it took < %.2f "
        "seconds to compile (%.2fs)", module_name, min_compile_time,
        compile_time_secs)
    return
  else:
    logger.debug(
        "'%s' took at least %.2f seconds to compile (%.2fs)",
        module_name, min_compile_time, compile_time_secs)

  try:
    compilation_cache.put_executable_and_time(
        cache_key, module_name, executable, backend, int(compile_time_secs))
  except Exception as ex:
    if _should_raise_persistent_cache_error(ex):
      raise
    warnings.warn(
        f"Error writing persistent compilation cache entry for "
        f"'{module_name}': {type(ex).__name__}: {ex}")

View on GitHub (pinned to 1e1c6a8fc0)

Solutions

Check free space and write permissions on the cache directory/bucket.
Grant the writer identity write access to the cache location.
Point the cache at a writable local path (e.g. JAX_COMPILATION_CACHE_DIR=/tmp/jax-cache) if remote writes are unreliable.
Set jax_raise_persistent_cache_errors=True to get the full traceback for diagnosis.

Example fix

# before
JAX_COMPILATION_CACHE_DIR=/read-only-mount/cache  # write fails
# after
JAX_COMPILATION_CACHE_DIR=/scratch/jax-cache
chmod -R u+w /scratch/jax-cache

Defensive patterns

Strategy: validation

Validate before calling

import os, tempfile
def cache_writable(d):
    try:
        os.makedirs(d, exist_ok=True)
        t = os.path.join(d, '.probe')
        open(t, 'w').close(); os.remove(t)
        return True
    except OSError:
        return False
assert cache_writable(os.environ['JAX_COMPILATION_CACHE_DIR'])

Try / catch

with warnings.catch_warnings(record=True) as caught:
    warnings.simplefilter('always')
    jitted_fn(x)
write_failures = [c for c in caught if 'writing persistent compilation cache' in str(c.message)]

Prevention

Provision cache on local NVMe/scratch with adequate space.
Verify write permissions on remote buckets before job submission.
Alert on this warning: it means every run pays full compile cost.

When it happens

Trigger: jit compilation completes but the cache write fails: disk full, read-only directory, missing cloud-storage write permissions, or serialization errors when storing the executable.

Common situations: Cache dir on a full ephemeral disk in containers; missing WRITE scope on a GCS service account; NFS mount mounted read-only; cache quota exceeded.

Related errors

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