GoogleContainerTools/jib · error · GradleException

_skaffoldFailIfJibOutOfDate requires jib.requiredVersion to

Error message

_skaffoldFailIfJibOutOfDate requires jib.requiredVersion to be set

What it means

CheckJibVersionTask is the Skaffold compatibility task (_skaffoldFailIfJibOutOfDate). Its @TaskAction checkVersion requires the jib.requiredVersion system property to be set; without it there is nothing to compare against, so it throws GradleException stating the property is required. With the property set, the task is a no-op since actual checking happens in JibPlugin.

Source

Thrown at jib-gradle-plugin/src/main/java/com/google/cloud/tools/jib/gradle/skaffold/CheckJibVersionTask.java:40

import org.gradle.api.GradleException;
import org.gradle.api.tasks.TaskAction;

/**
 * This internal Skaffold-related goal checks that the Jib plugin version is within some specified
 * range. It is only required so that older versions of Jib (prior to the introduction of the {@code
 * jib.requiredVersion} property) will error in such a way that it indicates the jib version is out
 * of date. This goal can be removed once there are no users of Jib prior to 1.4.0.
 *
 * <p>Expected use: {@code ./gradlew _skaffoldFailIfJibOutOfDate -Djib.requiredVersion='[1.4,2)'
 * jibDockerBuild --image=xxx}
 */
public class CheckJibVersionTask extends DefaultTask {

  /** Task Action, check if jib and skaffold versions are compatible. */
  @TaskAction
  public void checkVersion() {
    if (Strings.isNullOrEmpty(System.getProperty(JibPlugin.REQUIRED_VERSION_PROPERTY_NAME))) {
      throw new GradleException(
          JibPlugin.SKAFFOLD_CHECK_REQUIRED_VERSION_TASK_NAME
              + " requires "
              + JibPlugin.REQUIRED_VERSION_PROPERTY_NAME
              + " to be set");
    }
    // no-op as Jib version compatibility is actually checked in JibPlugin
  }
}

View on GitHub (pinned to fb949e2676)

Solutions

Run with -Djib.requiredVersion=<expected-jib-version> matching your Skaffold expectation
Only run _skaffoldFailIfJibOutOfDate as part of a Skaffold build, which sets the property automatically
Exclude the task in CI scripts that don't intend Skaffold version checking
Upgrade Skaffold/jib plugin pair so the injected property is provided

Example fix

// before
./gradlew _skaffoldFailIfJibOutOfDate
// after
./gradlew _skaffoldFailIfJibOutOfDate -Djib.requiredVersion=3.4.0

Defensive patterns

Strategy: validation

Validate before calling

if (gradle.startParameter.taskNames.contains('_skaffoldFailIfJibOutOfDate') &&
    !System.getProperty('jib.requiredVersion')) {
  throw new GradleException('_skaffoldFailIfJibOutOfDate must run with -Djib.requiredVersion=<version>')
}

Try / catch

try {
  checkJibVersionTask.execute()
} catch (GradleException e) {
  if (e.message.contains('requires jib.requiredVersion')) {
    logger.error('Run this task only via Skaffold, or pass -Djib.requiredVersion=<version>')
  } else { throw e }
}

Prevention

Only invoke _skaffoldFailIfJibOutOfDate from Skaffold-managed builds
Document that the task needs -Djib.requiredVersion when run manually
Exclude the Skaffold check task in plain CI pipelines
Keep Skaffold's jib version config current so it injects the property

When it happens

Trigger: Executing the _skaffoldFailIfJibOutOfDate task directly or as part of a Skaffold-driven build without -Djib.requiredVersion=<version> on the JVM/system properties.

Common situations: Running the task manually from Gradle outside Skaffold; a Skaffold config that omits the version it normally injects; CI invoking gradle _skaffoldFailIfJibOutOfDate without the -D flag.

Understand the failure class

Background: "--flag is required" and "must specify" CLI errors: how missing-required-flag validation works and how to fix it — this error's family across 20 libraries.

Related errors

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