GoogleContainerTools/jib · error · GradleException

HelpfulSuggestions.forIncompatibleBaseImageJavaVersionForGra

Error message

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

What it means

Jib refuses to build when the base image's Java major version is older than the project's compiled Java major version (e.g. project compiled with Java 17 but base image provides Java 11), because the container would fail at runtime with UnsupportedClassVersionError. Jib detects the base image's Java version and throws IncompatibleBaseImageJavaVersionException, wrapped by this GradleException with HelpfulSuggestions text naming both versions.

Source

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

              + 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

Upgrade the base image to one matching or exceeding the project's Java version, e.g. jib { from { image = 'eclipse-temurin:17' } }
Or lower the project's Java target (sourceCompatibility/targetCompatibility) to match the base image
Verify the base image actually provides the needed Java runtime by checking the image's documentation or running it and checking java -version
If intentional, pick a distroless/JRE tag variant explicitly matching the project major version

Example fix

// before (project targets Java 17)
jib { from { image = 'gcr.io/distroless/java:11' } }
// after
jib { from { image = 'gcr.io/distroless/java17-debian11' } }

Defensive patterns

Strategy: validation

Validate before calling

def projectJava = Integer.parseInt(project.java.targetCompatibility.majorVersion)
def baseImageJava = 17 // match your jib.from.image runtime
def baseImage = project.jib.from.image.get()
def javaBaseMap = ['gcr.io/distroless/java':11, 'gcr.io/distroless/java17-debian11':17]
assert javaBaseMap.getOrDefault(baseImage.split(':').first(), projectJava) >= projectJava : 'Base image Java too old for project'

Prevention

Always bump the base image tag when raising sourceCompatibility/targetCompatibility
Use versioned base image tags (e.g. distroless/java17) that encode the Java version
Add a CI check comparing project Java version to the configured base image

When it happens

Trigger: Running gradle jib or jibBuild where the project's sourceCompatibility/targetCompatibility Java major version exceeds the Java version found in the base image configured via jib.from.image (e.g. base image eclipse-temurin:11 while project targets 17).

Common situations: Upgrading the project to a newer JDK but forgetting to bump the base image; using an old Dockerfile-era base image tag; base image with no Java (Jib cannot match versions); copying base-image config from an older project.

Related errors

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