{"record":{"id":"1011f658155155b5","repo":"GoogleContainerTools/jib","slug":"cannot-run-jib-in-offline-mode-imagereference-n","errorCode":null,"errorMessage":"Cannot run Jib in offline mode; <imageReference> not found in local Jib cache","messagePattern":"Cannot run Jib in offline mode; <imageReference> not found in local Jib cache","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"jib-core/src/main/java/com/google/cloud/tools/jib/builder/steps/PullBaseImageStep.java","lineNumber":129,"sourceCode":"        eventHandlers.dispatch(LogEvent.progress(\"Getting scratch base image...\"));\n        ImmutableList.Builder<Image> images = ImmutableList.builder();\n        for (Platform platform : platforms) {\n          Image.Builder imageBuilder = Image.builder(buildContext.getTargetFormat());\n          imageBuilder.setArchitecture(platform.getArchitecture()).setOs(platform.getOs());\n          images.add(imageBuilder.build());\n        }\n        return new ImagesAndRegistryClient(images.build(), null);\n      }\n\n      eventHandlers.dispatch(\n          LogEvent.progress(\"Getting manifest for base image \" + imageReference + \"...\"));\n\n      if (buildContext.isOffline()) {\n        List<Image> images = getCachedBaseImages();\n        if (!images.isEmpty()) {\n          return new ImagesAndRegistryClient(images, null);\n        }\n        throw new IOException(\n            \"Cannot run Jib in offline mode; \" + imageReference + \" not found in local Jib cache\");\n\n      } else if (imageReference.getDigest().isPresent()) {\n        List<Image> images = getCachedBaseImages();\n        if (!images.isEmpty()) {\n          RegistryClient noAuthRegistryClient =\n              buildContext.newBaseImageRegistryClientFactory().newRegistryClient();\n          // TODO: passing noAuthRegistryClient may be problematic. It may return 401 unauthorized\n          // if layers have to be downloaded.\n          // https://github.com/GoogleContainerTools/jib/issues/2220\n          return new ImagesAndRegistryClient(images, noAuthRegistryClient);\n        }\n      }\n\n      Optional<ImagesAndRegistryClient> mirrorPull =\n          tryMirrors(buildContext, progressDispatcher.newChildProducer());\n      if (mirrorPull.isPresent()) {\n        return mirrorPull.get();","sourceCodeStart":111,"sourceCodeEnd":147,"githubUrl":"https://github.com/GoogleContainerTools/jib/blob/fb949e2676afbbd7dd7a1ef61e20251931325654/jib-core/src/main/java/com/google/cloud/tools/jib/builder/steps/PullBaseImageStep.java#L111-L147","documentation":"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.","triggerScenarios":"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().","commonSituations":"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.","solutions":["Remove the offline flag (-Djib.offline=false / drop --offline) and run once online to populate the cache","Run the build once with network access so the base image is downloaded into the Jib cache","Verify the exact base image reference (name:tag) in your build config matches one already in the local cache","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"],"exampleFix":"// before\nmvn jib:build -Djib.offline=true   // base image not in cache\n// after\nmvn jib:build                       // run online once to cache the base image\n// then offline builds work:\nmvn jib:build -Djib.offline=true","handlingStrategy":"fallback","validationCode":"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'","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Prime cache online before offline builds","Persist Jib cache in CI"],"tags":["offline","cache","jib","base-image"],"backgroundTag":"cache-miss","analyzedSha":"fb949e2676afbbd7dd7a1ef61e20251931325654","analyzedAt":"2026-09-06T14:04:09.491Z","contentChangedAt":"2026-09-06T14:04:09.491Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}