What causes "No or multiple layer files found for layer hash in directory: " in GoogleContainerTools/jib?

Clear the cache directory and rebuild the tar image

GoogleContainerTools/jib · error · CacheCorruptedException

No or multiple layer files found for layer hash <diffId> in

Error message

No or multiple layer files found for layer hash <diffId> in directory: <layerDirectory>

What it means

retrieveTarLayer(diffId) mirrors retrieve() but looks up a layer by its diff ID for tar-based (e.g. jib:buildTar / Docker daemon) flows. It expects exactly one layer file in the diff ID directory; any other count raises CacheCorruptedException with the diffId hash and directory in the message.

Source

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

   * Retrieves the {@link CachedLayer} for the local base image layer with the given diff ID.
   *
   * @param diffId the diff ID
   * @return the {@link CachedLayer} referenced by the diff ID, if found
   * @throws CacheCorruptedException if the cache was found to be corrupted
   * @throws IOException if an I/O exception occurs
   */
  Optional<CachedLayer> retrieveTarLayer(DescriptorDigest diffId)
      throws IOException, CacheCorruptedException {
    Path layerDirectory = cacheStorageFiles.getLocalDirectory().resolve(diffId.getHash());
    if (!Files.exists(layerDirectory)) {
      return Optional.empty();
    }

    try (Stream<Path> files = Files.list(layerDirectory)) {
      List<Path> layerFiles =
          files.filter(CacheStorageFiles::isLayerFile).collect(Collectors.toList());
      if (layerFiles.size() != 1) {
        throw new CacheCorruptedException(
            cacheStorageFiles.getCacheDirectory(),
            "No or multiple layer files found for layer hash "
                + diffId.getHash()
                + " in directory: "
                + layerDirectory);
      }

      Path layerFile = layerFiles.get(0);
      return Optional.of(
          CachedLayer.builder()
              .setLayerDigest(cacheStorageFiles.getDigestFromFilename(layerFile))
              .setLayerSize(Files.size(layerFile))
              .setLayerBlob(Blobs.from(layerFile))
              .setLayerDiffId(diffId)
              .build());
    }
  }

View on GitHub (pinned to fb949e2676)

Solutions

Clear the cache directory and rebuild the tar image
Ensure only one Jib build runs per cache directory at a time
Check the layer directory for stray files and remove them if you know the correct one
Upgrade Jib to the latest patch version

Example fix

// before
mvn jib:buildTar // fails: No or multiple layer files for sha256:diffid
// after
rm -rf ~/.cache/google-cloud-tools-java/jib && mvn jib:buildTar

Defensive patterns

Strategy: try-catch

Validate before calling

long n = Files.list(diffIdDir).filter(Files::isRegularFile).count();
if (n != 1) deleteRecursively(diffIdDir);

Try / catch

try {
  jibBuildTar();
} catch (CacheCorruptedException e) {
  wipeCache();
  jibBuildTar();
}

Prevention

Let builds finish before shutting down CI agents
Use a dedicated cache per job in CI
Avoid sharing cache volumes between Jib versions

When it happens

Trigger: retrieveTarLayer() is called and the layer directory keyed by diffId contains zero or multiple files recognized as layer files by CacheStorageFiles::isLayerFile.

Common situations: Interruption during tar layer extraction/writing, external tools modifying the cache, cache shared across Jib versions with different file naming so extra/missing files appear.

Related errors

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