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

Fix the extension (or its input) so buildPlan.baseImage is a valid reference like 'gcr.io/project/app:tag'

GoogleContainerTools/jib · error · JibPluginExtensionException

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

Error message

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

What it means

GradleProjectProperties.runPluginExtensions validates the base image produced by an extension by calling ImageReference.parse(buildPlan.getBaseImage()); on InvalidImageReferenceException it throws JibPluginExtensionException naming the extension class with 'invalid base image reference: <baseImage>'. The extension set a base image string that is not a valid image reference.

Source

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

      return jibContainerBuilder;
    }

    List<JibGradlePluginExtension<?>> loadedExtensions = extensionLoader.get();
    JibGradlePluginExtension<?> 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().get()" (Object) to Action<T> and "extension"
  // (JibGradlePluginExtension<?>) to JibGradlePluginExtension<T> where T is the extension-defined
  // config type (as requested by "JibGradlePluginExtension.getExtraConfigType()").
  @SuppressWarnings({"unchecked"})
  private <T> ContainerBuildPlan runPluginExtension(
      Optional<Class<T>> extraConfigType,
      JibGradlePluginExtension<?> extension,
      ExtensionConfiguration config,
      ContainerBuildPlan buildPlan)
      throws JibPluginExtensionException {
    T extraConfig = null;
    Optional<Object> configs = config.getExtraConfiguration();

View on GitHub (pinned to fb949e2676)

Solutions

Fix the extension (or its input) so buildPlan.baseImage is a valid reference like 'gcr.io/project/app:tag'
Validate the property/env value feeding the base image before running the extension
Set jib.from.image explicitly so extensions that pass it through inherit a valid value

Example fix

// before (inside extension)
String base = System.getenv("BASE_IMAGE"); // may be null
ImageReference.parse(base);
// after
String base = Objects.requireNonNullElse(System.getenv("BASE_IMAGE"), "gcr.io/distroless/java17-debian11");

Defensive patterns

Strategy: validation

Validate before calling

// inside the extension, before returning the build plan
import com.google.cloud.tools.jib.api.ImageReference
Objects.requireNonNull(plan.baseImage, 'baseImage must be set')
ImageReference.parse(plan.baseImage) // throws early with a clear message

Prevention

Parse base image strings with ImageReference.parse at extension config time
Never let env vars/properties flow into baseImage without a default and validation
Keep jib.from.image set even when extensions modify it, so pass-through stays valid

When it happens

Trigger: A plugin extension's extend() returns/updates a ContainerBuildPlan whose baseImage field is null, empty, or syntactically invalid (spaces, uppercase repo, bad tag/digest); runPluginExtensions then parses it and fails.

Common situations: Custom extension code computing the base image from an environment variable or Gradle property that is unset or malformed; extension bug building the build plan with a placeholder value.

Related errors

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