GoogleContainerTools/jib · error · CacheDirectoryCreationException

CacheDirectoryCreationException wrapping IOException from ca

Error message

CacheDirectoryCreationException wrapping IOException from cache directory creation

What it means

Cache.withDirectory creates the given cache directory before constructing the Cache. If Files.createDirectories throws an IOException (permissions, path is a file, disk issues), the IOException is wrapped in a CacheDirectoryCreationException so callers get a single, typed failure instead of a raw IOException.

Source

Thrown at jib-core/src/main/java/com/google/cloud/tools/jib/cache/Cache.java:59

 *
 * <p>This class is immutable and safe to use across threads.
 */
@Immutable
public class Cache {

  /**
   * Initializes the cache using {@code cacheDirectory} for storage.
   *
   * @param cacheDirectory the directory for the cache. Creates the directory if it does not exist.
   * @return a new {@link Cache}
   * @throws CacheDirectoryCreationException if an I/O exception occurs when creating cache
   *     directory
   */
  public static Cache withDirectory(Path cacheDirectory) throws CacheDirectoryCreationException {
    try {
      Files.createDirectories(cacheDirectory);
    } catch (IOException ex) {
      throw new CacheDirectoryCreationException(ex);
    }
    return new Cache(new CacheStorageFiles(cacheDirectory));
  }

  private final CacheStorageWriter cacheStorageWriter;
  private final CacheStorageReader cacheStorageReader;

  private Cache(CacheStorageFiles cacheStorageFiles) {
    cacheStorageWriter = new CacheStorageWriter(cacheStorageFiles);
    cacheStorageReader = new CacheStorageReader(cacheStorageFiles);
  }

  /**
   * Saves image metadata (a manifest list and a list of manifest/container configuration pairs) for
   * an image reference.
   *
   * @param imageReference the image reference to save the metadata for
   * @param metadata the image metadata

View on GitHub (pinned to fb949e2676)

Solutions

1. Check permissions on the cache directory path and its parent (the build user must be able to create/write it)
2. If the path exists as a file, remove it or pick a different cache directory
3. Set the jib cache directory explicitly to a writable location (jib.cacheDirectory Maven / --imageBuildCache Gradle or JibSystemProperties)
4. Ensure the filesystem is writable and has free space (read-only root fs: mount a writable volume for the cache)

Example fix

// before
Cache cache = Cache.withDirectory(Paths.get("/var/cache/jib"));  // read-only dir
// after
Cache cache = Cache.withDirectory(Paths.get(System.getProperty("java.io.tmpdir"), "jib-cache"));

[ -e "$CACHE_DIR" ] && [ ! -d "$CACHE_DIR" ] && echo 'cache path is a file'; [ -d "$CACHE_DIR" ] && [ ! -w "$CACHE_DIR" ] && echo 'cache dir not writable'

When it happens

Trigger: Calling Cache.withDirectory(path) when the path exists as a regular file, the process lacks write permission on the parent, the filesystem is read-only or full, or the path component is invalid/unwritable.

Common situations: Custom jib cache directory configured to an unwritable location in CI; a file accidentally occupying the cache path; read-only container filesystems; running under a service user without access to ~/.cache; NFS volumes with permission quirks.

Understand the failure class

Background: mkdir permission denied (EACCES): failed to create directory errors explained — this error's family across 32 libraries.

Related errors

• Unable to create cache directory for project path: ${path} -
• Cannot run Jib in offline mode; <imageReference> not found i
• Layer file did not include valid hash: <layerFile>
• Manifest cache empty
• Manifest(s) missing

AI-assisted analysis of GoogleContainerTools/jib@fb949e2676 (2026-09-06). Data as JSON: /api/errors/505bc88953765e01. Report an issue: GitHub.