GoogleContainerTools/jib · error · GradleException

HelpfulSuggestions.forIncompatibleBaseImageJavaVersionForGra

Error message

HelpfulSuggestions.forIncompatibleBaseImageJavaVersionForGradle(${ex.getBaseImageMajorJavaVersion()}, ${ex.getProjectMajorJavaVersion()})

What it means

BuildTarTask.buildTar catches IncompatibleBaseImageJavaVersionException and converts it to a GradleException using HelpfulSuggestions.forIncompatibleBaseImageJavaVersionForGradle. Jib throws it when the project's Java major version is newer than the Java version the chosen base image supports (Distroless/Java base images are version-pinned), so the app would not run on that base image.

Source

Thrown at jib-gradle-plugin/src/main/java/com/google/cloud/tools/jib/gradle/BuildTarTask.java:193

              + ex.getInvalidFilesModificationTime(),
          ex);

    } catch (InvalidCreationTimeException ex) {
      throw new GradleException(
          "container.creationTime should be an ISO 8601 date-time (see "
              + "DateTimeFormatter.ISO_DATE_TIME) or a special keyword (\"EPOCH\", "
              + "\"USE_CURRENT_TIMESTAMP\"): "
              + ex.getInvalidCreationTime(),
          ex);

    } catch (JibPluginExtensionException ex) {
      String extensionName = ex.getExtensionClass().getName();
      throw new GradleException(
          "error running extension '" + extensionName + "': " + ex.getMessage(), ex);

    } catch (IncompatibleBaseImageJavaVersionException ex) {
      throw new GradleException(
          HelpfulSuggestions.forIncompatibleBaseImageJavaVersionForGradle(
              ex.getBaseImageMajorJavaVersion(), ex.getProjectMajorJavaVersion()),
          ex);

    } catch (InvalidImageReferenceException ex) {
      throw new GradleException(
          HelpfulSuggestions.forInvalidImageReference(ex.getInvalidReference()), ex);

    } catch (ExtraDirectoryNotFoundException ex) {
      throw new GradleException(
          "extraDirectories.paths contain \"from\" directory that doesn't exist locally: "
              + ex.getPath(),
          ex);
    } finally {
      tempDirectoryProvider.close();
      TaskCommon.finishUpdateChecker(projectProperties, updateCheckFuture);
      projectProperties.waitForLoggingThread();
    }
  }

View on GitHub (pinned to fb949e2676)

Solutions

Update the base image to one matching or exceeding the project Java version, e.g. 'gcr.io/distroless/java17-debian11' or 'gcr.io/distroless/java21-debian12'
Or lower the project's Java target (sourceCompatibility/toolchain) to match the base image
Use a version-agnostic base image (e.g. 'eclipse-temurin:17-jre') where Jib cannot infer a conflict

Example fix

// before
jib { from { image = 'gcr.io/distroless/java11-debian11' } } // project targets Java 17
// after
jib { from { image = 'gcr.io/distroless/java17-debian11' } }

Defensive patterns

Strategy: validation

Validate before calling

def projectJava = java.sourceCompatibility.majorVersion.toInteger()
def baseImageRequires = ['gcr.io/distroless/java': 8, 'gcr.io/distroless/java11-debian11': 11]
assert projectJava <= (baseImageRequires[jib.from.image.get()] ?: 99) : 'base image Java version too old for project'

Prevention

Keep the distroless base image tag in sync with sourceCompatibility/toolchain (java8/java11/java17/java21)
Centralize the Java version in one variable used by both java extension and jib.from.image
Prefer version-suffixed base image tags; avoid 'latest'

When it happens

Trigger: Building with from { image = 'gcr.io/distroless/java' } (Java 8) or a Java-11 base image while the project compiles with Java 17+ (sourceCompatibility/targetCompatibility or toolchain), so Jib refuses the combination.

Common situations: Upgrading a project to Java 17 or 21 without updating the distroless base image tag from 'distroless/java' or 'distroless/java11' to 'distroless/java17'/'distroless/java21'; CI toolchain bump not mirrored in jib.from.image.

Related errors

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