What causes "invalid base image reference: ${buildPlan.getBaseImage()}" in GoogleContainerTools/jib?

Log/print buildPlan.getBaseImage() in your extension to see the actual invalid value and fix the string generation.

GoogleContainerTools/jib · error · JibPluginExtensionException

invalid base image reference: ${buildPlan.getBaseImage()}

Error message

invalid base image reference: ${buildPlan.getBaseImage()}

What it means

During Jib Maven plugin extension processing, the base image string produced by a plugin extension's build plan could not be parsed as a valid container image reference. runPluginExtensions validates the extension-modified plan's base image with ImageReference.parse and wraps the resulting InvalidImageReferenceException in a JibPluginExtensionException.

Source

Thrown at jib-maven-plugin/src/main/java/com/google/cloud/tools/jib/maven/MavenProjectProperties.java:631

    // Extensions might support both approaches (injection and JDK service loader) at the same
    // time for compatibility reasons.
    List<JibMavenPluginExtension<?>> loadedExtensions = new ArrayList<>(injectedExtensions);
    loadedExtensions.addAll(extensionLoader.get());
    JibMavenPluginExtension<?> extension = null;
    ContainerBuildPlan buildPlan = jibContainerBuilder.toContainerBuildPlan();
    try {
      for (ExtensionConfiguration config : extensionConfigs) {
        extension = findConfiguredExtension(loadedExtensions, config);

        log(LogEvent.lifecycle("Running extension: " + config.getExtensionClass()));
        buildPlan =
            runPluginExtension(extension.getExtraConfigType(), extension, config, buildPlan);
        ImageReference.parse(buildPlan.getBaseImage()); // to validate image reference
      }
      return jibContainerBuilder.applyContainerBuildPlan(buildPlan);

    } catch (InvalidImageReferenceException ex) {
      throw new JibPluginExtensionException(
          Verify.verifyNotNull(extension).getClass(),
          "invalid base image reference: " + buildPlan.getBaseImage(),
          ex);
    }
  }

  // Unchecked casting: "getExtraConfiguration()" (Optional<Object>) to Object<T> and "extension"
  // (JibMavenPluginExtension<?>) to JibMavenPluginExtension<T> where T is the extension-defined
  // config type (as requested by "JibMavenPluginExtension.getExtraConfigType()").
  @SuppressWarnings({"unchecked"})
  private <T> ContainerBuildPlan runPluginExtension(
      Optional<Class<T>> extraConfigType,
      JibMavenPluginExtension<?> extension,
      ExtensionConfiguration config,
      ContainerBuildPlan buildPlan)
      throws JibPluginExtensionException {
    Optional<T> extraConfig = Optional.empty();
    Optional<Object> configs = config.getExtraConfiguration();

View on GitHub (pinned to fb949e2676)

Solutions

Log/print buildPlan.getBaseImage() in your extension to see the actual invalid value and fix the string generation.
Validate the base image with ImageReference.parse() inside your extension before returning the build plan to fail fast with a clearer message.
Ensure any properties/env vars feeding the base image name are set and non-empty at build time.
Check that registry, repository, tag, and digest components conform to Docker reference grammar (no invalid characters, port syntax, empty tags).

Example fix

// before (in extension)
String base = System.getProperty("base.image");
plan.setToBaseImage(base);

// after
String base = Objects.requireNonNullElse(System.getProperty("base.image"), "eclipse-temurin:17");
ImageReference.parse(base); // fail fast with clear message
plan.setToBaseImage(base);

Defensive patterns

Strategy: validation

Validate before calling

// In your extension, before returning the build plan
import com.google.cloud.tools.jib.api.ImageReference;
String base = buildPlan.getBaseImage();
ImageReference.parse(base); // throws InvalidImageReferenceException early with clear context
if (base == null || base.isBlank()) throw new IllegalStateException("base image must be set");

Type guard

boolean isValidImageRef(String s) {
  return s != null && s.matches("[a-zA-Z0-9][a-zA-Z0-9._-]*(?::[0-9]+)?(?:/[a-zA-Z0-9._/-]+)*(?::[a-zA-Z0-9._-]+)?(?:@[a-zA-Z0-9+:._-]+)?");
}

Try / catch

try {
  // run jib build with extensions
} catch (JibPluginExtensionException e) {
  if (e.getMessage().startsWith("invalid base image reference")) {
    // inspect extension logic producing the base image
  }
  throw e;
}

Prevention

Validate base image strings with ImageReference.parse inside extensions before returning plans.
Never build base image strings from possibly-empty properties/env vars without defaults.
Use ImageReference.of(...) or ImageReference.parse(...) APIs instead of raw string concatenation.
Add a unit test for your extension that asserts the produced plan's base image parses.

When it happens

Trigger: A Jib plugin extension (run via <pluginExtensions> configuration) returns a ContainerBuildPlan whose baseImage is null, empty, malformed, or contains invalid characters/registry syntax, causing ImageReference.parse to throw.

Common situations: Custom extension code sets the base image from a property or env var that is unset/empty; extension builds the image string by concatenation producing 'registry/image:tag:' style malformations; port or digest formatting mistakes in generated references.

Understand the failure class

Background: "Invalid URL" errors: why new URL(), URI.parse, and reqwest::Url reject your string — missing scheme, whitespace, and bad path format — this error's family across 39 libraries.

Related errors

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