GoogleContainerTools/jib · error · GradleException

Invalid image reference ${invalidReference}, perhaps you sho

Error message

Invalid image reference ${invalidReference}, perhaps you should check that the reference is formatted correctly according to https://docs.docker.com/engine/reference/commandline/tag/#extended-description
For example, slash-separated name components cannot have uppercase letters

What it means

Thrown when the configured image reference (jib.to.image, jib.from.image, tags, etc.) cannot be parsed as a valid Docker/OCI image reference. Jib wraps InvalidImageReferenceException and appends HelpfulSuggestions.forInvalidImageReference, which points to Docker's tag documentation and notes that slash-separated name components cannot contain uppercase letters.

Source

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

          "container.creationTime should be an ISO 8601 date-time (see "
              + "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 BuildDockerTask setJibExtension(JibExtension jibExtension) {
    this.jibExtension = jibExtension;
    return this;

View on GitHub (pinned to fb949e2676)

Solutions

Lowercase all repository/name components, e.g. 'gcr.io/myproject/myapp'
Validate the reference against Docker's tag/name grammar (registry/repo:tag) — see the URL in the message
Remove spaces or illegal characters; quote parts that undergo Gradle string interpolation
Add an explicit tag (e.g. ':latest' or a version) if the reference is ambiguous

Example fix

// before
jib { to { image = 'gcr.io/MyProject/MyApp' } }
// after
jib { to { image = 'gcr.io/myproject/myapp:v1.0.0' } }

Defensive patterns

Strategy: validation

Validate before calling

def ref = jib.to.image
if (ref && (ref =~ /\s|[A-Z]/)) {
  throw new GradleException("Image reference contains invalid characters (spaces/uppercase): $ref")
}

Try / catch

try { jibBuild.run() } catch (InvalidImageReferenceException | GradleException e) { if (e.message?.contains('Invalid image reference')) { logger.error(e.message + " — lowercase repo components, check registry/repo:tag format") }; throw e }

Prevention

Lowercase all image name/repository components
Interpolate Gradle properties carefully — avoid injecting invalid characters
Always validate registry URLs and include explicit tags
Test the reference with 'docker tag' parsing before adding it to Jib config

When it happens

Trigger: Setting to.image or from.image with uppercase characters in a repository path (e.g. 'MyApp'), missing registry/tag separators, invalid characters (spaces, underscores in wrong position), or malformed registry hostnames.

Common situations: Using a project name with uppercase letters directly as the image name (common on macOS/Windows where Docker allows it locally), typos in registry URLs, or interpolating Gradle project properties that contain invalid characters into the image reference.

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/02b744b44c67ecb7. Report an issue: GitHub.