GoogleContainerTools/jib · error · InvalidImageReferenceException

${reference}

Error message

${reference}

What it means

ImageReference.parse uses a regex (REFERENCE_PATTERN) to split an image reference into registry, repository, tag, and digest. If the string does not match the pattern at all (or fewer than 4 groups match), it throws InvalidImageReferenceException wrapping the original string. This is the first-line format validation for any image reference string in jib.

Source

Thrown at jib-core/src/main/java/com/google/cloud/tools/jib/api/ImageReference.java:105

   *
   * <p>See <a
   * href="https://docs.docker.com/engine/reference/commandline/tag/#extended-description">https://docs.docker.com/engine/reference/commandline/tag/#extended-description</a>
   * for a description of valid image reference format. Note, however, that the image reference is
   * referred confusingly as {@code tag} on that page.
   *
   * @param reference the string to parse
   * @return an {@link ImageReference} parsed from the string
   * @throws InvalidImageReferenceException if {@code reference} is formatted incorrectly
   */
  public static ImageReference parse(String reference) throws InvalidImageReferenceException {
    if (reference.equals(SCRATCH)) {
      return ImageReference.scratch();
    }

    Matcher matcher = REFERENCE_PATTERN.matcher(reference);

    if (!matcher.find() || matcher.groupCount() < 4) {
      throw new InvalidImageReferenceException(reference);
    }

    String registry = matcher.group(1);
    String repository = matcher.group(2);
    String tag = matcher.group(3);
    String digest = matcher.group(4);

    // If no registry was matched, use Docker Hub by default.
    if (Strings.isNullOrEmpty(registry)) {
      registry = DOCKER_HUB_REGISTRY;
    }

    if (Strings.isNullOrEmpty(repository)) {
      throw new InvalidImageReferenceException(reference);
    }
    /*
     * If a registry was matched but it does not contain any dots or colons, it should actually be
     * part of the repository unless it is "localhost".

View on GitHub (pinned to fb949e2676)

Solutions

1. Check the reference string matches docker image syntax: [registry/]repository[:tag][@digest]
2. Print/log the exact string thrown — the exception message contains the full invalid reference
3. Ensure variables used to build the reference are non-empty and contain no illegal characters
4. Catch InvalidImageReferenceException and validate user input before calling jib APIs

Example fix

// before
Jib.from(imageNameFromConfig); // imageNameFromConfig may be empty
// after
if (imageNameFromConfig == null || imageNameFromConfig.isEmpty() || !imageNameFromConfig.matches("[a-zA-Z0-9._/-]+(:[a-zA-Z0-9._-]+)?")) {
  throw new IllegalArgumentException("Invalid image name: " + imageNameFromConfig);
}
Jib.from(imageNameFromConfig);

boolean validRef = ref != null && ref.matches("([a-zA-Z0-9.:-]+/)?[a-z0-9._/-]+(:[a-zA-Z0-9._-]+)?(@[a-zA-Z0-9]+:[a-f0-9]{64})?");

if (ref == null || ref.isEmpty() || !ref.matches("([a-zA-Z0-9.:-]+/)?[a-z0-9._/-]+(:[a-zA-Z0-9._-]+)?")) return Optional.empty();

try { return ImageReference.parse(ref); } catch (InvalidImageReferenceException e) { throw new IllegalArgumentException("Bad image reference: " + e.getMessage(), e); }

When it happens

Trigger: Calling ImageReference.parse (directly or via JibContainerBuilder.from/fromRegistry) with a string that does not match docker reference syntax: empty string, illegal characters, malformed 'registry/repo:tag@digest' structure, or an invalid port/registry segment.

Common situations: Typos in image names (spaces, invalid chars), interpolating empty variables into image names, passing a bare tag like ':latest', or references from user config/CLI args that were never validated.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• Invalid image reference ${invalidReference}, perhaps you sho
• HelpfulSuggestions.forInvalidImageReference(${ex.getInvalidR
• octalPermissions must be a 3-digit octal number (000-777)
• The class file (${jarEntry}) is of an invalid format.
• Reached end of class file (${jarEntry}) before being able to

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