GoogleContainerTools/jib · error · GradleException

HelpfulSuggestions.forInvalidImageReference(${ex.getInvalidR

Error message

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

What it means

BuildTarTask.buildTar catches InvalidImageReferenceException and wraps HelpfulSuggestions.forInvalidImageReference(ex.getInvalidReference()) in a GradleException. Jib throws this when a configured image reference (base image, target image, etc.) cannot be parsed as a valid container image reference (registry/repository:tag@digest format).

Source

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

              + "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 BuildTarTask setJibExtension(JibExtension jibExtension) {
    this.jibExtension = jibExtension;
    return this;
  }

View on GitHub (pinned to fb949e2676)

Solutions

Fix the reference format: lowercase repository, no spaces, optional registry host, tag <= 128 chars, e.g. 'gcr.io/my-project/app:1.0.0'
Check that any Gradle property interpolated into the image name actually resolves (print it in a doFirst or validate task)
Validate locally with ImageReference.parse(...) or a regex before passing dynamic values

Example fix

// before
jib.to.image = 'gcr.io/My-Project/App:latest release'
// after
jib.to.image = 'gcr.io/my-project/app:latest-release'

Defensive patterns

Strategy: validation

Validate before calling

def validRef = { s -> s ==~ /[a-z0-9]+((\.|__|-+)[a-z0-9]+)*(\/[^\sA-Z]+)?(:[\w][\w.-]{0,127})?(@sha256:[a-f0-9]{64})?/ }
assert validRef(jib.to.image.get()) && validRef(jib.from.image.get())

Prevention

Keep image names lowercase, no spaces, tags <= 128 chars
Avoid building image names by string concatenation with possibly-empty properties
Log the resolved image name during build-script configuration to catch interpolation issues early

When it happens

Trigger: jib.from.image or jib.to.image contains illegal characters, spaces, uppercase in repository name, empty string, a tag longer than 128 chars, or malformed digest syntax, and a jib task (here jibBuildTar) attempts to parse it.

Common situations: Typo like 'my repo/app'; property interpolation yielding empty string ($ failing to resolve); using a tag with invalid characters; accidentally pasting a full 'docker pull' command line as the image name.

Related errors

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