GoogleContainerTools/jib · error · IOException

Cannot run Jib in offline mode; <imageReference> not found i

Error message

Cannot run Jib in offline mode; <imageReference> not found in local Jib cache

What it means

When Jib runs in offline mode (-Djib.offline=true or --offline), it resolves the base image exclusively from the local Jib cache instead of contacting a registry. If no cached image for the given <imageReference> exists, it throws this IOException so the build fails fast instead of attempting a network call.

Source

Thrown at jib-core/src/main/java/com/google/cloud/tools/jib/builder/steps/PullBaseImageStep.java:129

        eventHandlers.dispatch(LogEvent.progress("Getting scratch base image..."));
        ImmutableList.Builder<Image> images = ImmutableList.builder();
        for (Platform platform : platforms) {
          Image.Builder imageBuilder = Image.builder(buildContext.getTargetFormat());
          imageBuilder.setArchitecture(platform.getArchitecture()).setOs(platform.getOs());
          images.add(imageBuilder.build());
        }
        return new ImagesAndRegistryClient(images.build(), null);
      }

      eventHandlers.dispatch(
          LogEvent.progress("Getting manifest for base image " + imageReference + "..."));

      if (buildContext.isOffline()) {
        List<Image> images = getCachedBaseImages();
        if (!images.isEmpty()) {
          return new ImagesAndRegistryClient(images, null);
        }
        throw new IOException(
            "Cannot run Jib in offline mode; " + imageReference + " not found in local Jib cache");

      } else if (imageReference.getDigest().isPresent()) {
        List<Image> images = getCachedBaseImages();
        if (!images.isEmpty()) {
          RegistryClient noAuthRegistryClient =
              buildContext.newBaseImageRegistryClientFactory().newRegistryClient();
          // TODO: passing noAuthRegistryClient may be problematic. It may return 401 unauthorized
          // if layers have to be downloaded.
          // https://github.com/GoogleContainerTools/jib/issues/2220
          return new ImagesAndRegistryClient(images, noAuthRegistryClient);
        }
      }

      Optional<ImagesAndRegistryClient> mirrorPull =
          tryMirrors(buildContext, progressDispatcher.newChildProducer());
      if (mirrorPull.isPresent()) {
        return mirrorPull.get();

View on GitHub (pinned to fb949e2676)

Solutions

1. Remove the offline flag (-Djib.offline=false / drop --offline) and run once online to populate the cache
2. Run the build once with network access so the base image is downloaded into the Jib cache
3. Verify the exact base image reference (name:tag) in your build config matches one already in the local cache
4. Point to a locally available image: build/import it via a local Docker daemon (jib:dockerBuild with from image from daemon) or pre-seed the cache

Example fix

// before
mvn jib:build -Djib.offline=true   // base image not in cache
// after
mvn jib:build                       // run online once to cache the base image
// then offline builds work:
mvn jib:build -Djib.offline=true

test -d ~/.cache/google-cloud-tools-jib && grep -r "$(echo $BASE_IMAGE | md5sum | cut -d' ' -f1)" ~/.cache/google-cloud-tools-jib >/dev/null || echo 'cache miss: build online first'

When it happens

Trigger: Running jib:build/jib:dockerBuild with the offline flag enabled while the base image reference has never been pulled into the local Jib cache (~/.cache/google-cloud-tools-jib or platform-specific cache dir); getCachedBaseImages() returns an empty list in PullBaseImageStep.call().

Common situations: CI or dev machines with no network access using --offline for the first time; cache directories cleared by cleanup jobs; referencing a base image by digest/tag that was cached on another machine; switching base images while offline.

Related errors

• Cannot run Jib in offline mode; local Jib cache for base ima
• The input JAR (${jarPath}) is compiled with Java ${jarJavaVe
• the configured platform (%s/%s) doesn't match the platform (
• CacheDirectoryCreationException wrapping IOException from ca
• Layer file did not include valid hash: <layerFile>

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