GoogleContainerTools/jib · error · RuntimeException

Unable to create cache directory for project path: ${path} -

Error message

Unable to create cache directory for project path: ${path} - you can try to configure --project-cache manually

What it means

Jib CLI computes a hash of the project path and creates a per-project cache directory under the base cache location. If creating that directory throws an IOException or SecurityException, it wraps the failure in a RuntimeException with this message. It tells you the CLI could not materialize its local build cache for your project and suggests setting --project-cache manually.

Source

Thrown at jib-cli/src/main/java/com/google/cloud/tools/jib/cli/CacheDirectories.java:75

                Paths.get(System.getProperty("java.io.tmpdir"))
                    .resolve("jib-cli-cache")
                    .resolve("projects")
                    .resolve(getProjectCacheDirectoryFromProject(contextRoot))));
  }

  @VisibleForTesting
  static String getProjectCacheDirectoryFromProject(Path path) {
    try {
      byte[] hashedBytes =
          MessageDigest.getInstance("SHA-256")
              .digest(path.toFile().getCanonicalPath().getBytes(Charsets.UTF_8));
      StringBuilder stringBuilder = new StringBuilder(2 * hashedBytes.length);
      for (byte b : hashedBytes) {
        stringBuilder.append(String.format("%02x", b));
      }
      return stringBuilder.toString();
    } catch (IOException | SecurityException ex) {
      throw new RuntimeException(
          "Unable to create cache directory for project path: "
              + path
              + " - you can try to configure --project-cache manually",
          ex);
    } catch (NoSuchAlgorithmException ex) {
      throw new RuntimeException(
          "SHA-256 algorithm implementation not found - might be a broken JVM");
    }
  }

  public CacheDirectories(@Nullable Path baseImageCache, Path projectCache) {
    this.baseImageCache = baseImageCache;
    this.projectCache = projectCache;
  }

  public Optional<Path> getBaseImageCache() {
    return Optional.ofNullable(baseImageCache);
  }

View on GitHub (pinned to fb949e2676)

Solutions

Pass --project-cache=/some/writable/path to point the cache at a writable directory.
Check and fix permissions on the default cache location (usually under the user home) so the process can create directories there.
Ensure sufficient disk space and that no file exists where the cache directory should be created.
If running under a SecurityManager, grant write permission to the cache path or disable it.

Example fix

// before
jib ... // uses default cache under unwritable $HOME/.cache
// after
jib ... --project-cache=/tmp/jib-cache

Defensive patterns

Strategy: fallback

Validate before calling

Path cache = Paths.get(System.getProperty("user.home"), ".cache", "jib");
if (!Files.isWritable(cache)) {
  args.add("--project-cache=/tmp/jib-cache");
}

Try / catch

try {
  runJib(args);
} catch (RuntimeException e) {
  if (e.getMessage() != null && e.getMessage().startsWith("Unable to create cache directory")) {
    runJib(withProjectCache(args, "/tmp/jib-cache"));
  } else throw e;
}

Prevention

Always run Jib in an environment with a writable user home or explicit --project-cache
Set --project-cache in CI containers running as non-root
Monitor disk space on cache volumes

When it happens

Trigger: Calling CacheDirectories.getProjectCacheDirectoryFromProject (via from) when Files.createDirectories on the derived cache path throws IOException (e.g. parent dir not writable, disk full, path too long) or SecurityException (security manager denies write).

Common situations: Read-only home or shared cache directory, running in a container as non-root with unwritable /home, NFS-mounted cache location with permission issues, overly restrictive SecurityManager in CI.

Understand the failure class

Background: "failed to write file", "Could not save figure", "Error saving remote file" — file write failed: causes and fixes across languages and libraries — this error's family across 38 libraries.

Related errors

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