GoogleContainerTools/jib · error · GradleException

HelpfulSuggestions.forInvalidImageReference(${ex.getInvalidR

Error message

HelpfulSuggestions.forInvalidImageReference(${ex.getInvalidReference()})

What it means

Jib validates image references (jib.to.image, jib.from.image, --image flag) before any registry/network work and throws InvalidImageReferenceException when the string is not a syntactically valid image reference (bad registry, tag, or digest form). The Gradle task converts it to a GradleException with HelpfulSuggestions suggesting correct syntax, passing along the invalid reference text.

Source

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

              + "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();
    }
  }

  @Override
  public BuildImageTask setJibExtension(JibExtension jibExtension) {
    this.jibExtension = jibExtension;
    return this;
  }

View on GitHub (pinned to fb949e2676)

Solutions

Correct the image reference syntax in jib.to.image / jib.from.image to a full valid form like 'registry/project/image:tag'
Check that any Gradle property or environment variable interpolated into the image value actually resolves (don't pass through unresolved placeholders)
Use the --image flag to override: gradle jib --image myregistry.example.com/project/app:1.0
Test the reference locally with 'docker pull <ref>' to confirm it is a valid, resolvable reference

Example fix

// before
jib { to { image = "${System.getenv('IMAGE_NAME')}" } } // IMAGE_NAME unset -> empty/invalid
// after
jib {
  to {
    image = System.getenv('IMAGE_NAME') ?: 'gcr.io/my-project/my-app:latest'
  }
}

Defensive patterns

Strategy: validation

Validate before calling

def ref = project.jib.to.image.getOrElse('')
if (!ref || !(ref ==~ /^[a-zA-Z0-9][a-zA-Z0-9._\-/:]*(:[a-zA-Z0-9._\-]+)?(@sha256:[a-f0-9]{64})?$/)) {
  throw new GradleException("Invalid image reference: '$ref'")
}

Prevention

Never interpolate possibly-unset env vars/properties into image names without a default
Use fully qualified references: registry/project/image:tag
Test references locally with docker pull before wiring them into Jib

When it happens

Trigger: Running gradle jib/jibBuild where jib.to.image or jib.from.image contains an invalid reference: empty string, illegal characters, missing repository name after a registry host, malformed port, or malformed digest.

Common situations: Typos like 'myregistry:5000/app' with bad tag syntax; unexpanded Gradle property (e.g. 'jib.to.image = "${env.IMAGE}"' resolving to literal text or empty); using docker-style shorthand Jib cannot parse; copy-pasting an image name with quotes/spaces.

Related errors

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