{"record":{"id":"d86a2f40186cc7f4","repo":"GoogleContainerTools/jib","slug":"reference","errorCode":null,"errorMessage":"${reference}","messagePattern":"\\$\\{reference\\}","errorType":"validation","errorClass":"InvalidImageReferenceException","httpStatus":null,"severity":"error","filePath":"jib-core/src/main/java/com/google/cloud/tools/jib/api/ImageReference.java","lineNumber":105,"sourceCode":"   *\n   * <p>See <a\n   * href=\"https://docs.docker.com/engine/reference/commandline/tag/#extended-description\">https://docs.docker.com/engine/reference/commandline/tag/#extended-description</a>\n   * for a description of valid image reference format. Note, however, that the image reference is\n   * referred confusingly as {@code tag} on that page.\n   *\n   * @param reference the string to parse\n   * @return an {@link ImageReference} parsed from the string\n   * @throws InvalidImageReferenceException if {@code reference} is formatted incorrectly\n   */\n  public static ImageReference parse(String reference) throws InvalidImageReferenceException {\n    if (reference.equals(SCRATCH)) {\n      return ImageReference.scratch();\n    }\n\n    Matcher matcher = REFERENCE_PATTERN.matcher(reference);\n\n    if (!matcher.find() || matcher.groupCount() < 4) {\n      throw new InvalidImageReferenceException(reference);\n    }\n\n    String registry = matcher.group(1);\n    String repository = matcher.group(2);\n    String tag = matcher.group(3);\n    String digest = matcher.group(4);\n\n    // If no registry was matched, use Docker Hub by default.\n    if (Strings.isNullOrEmpty(registry)) {\n      registry = DOCKER_HUB_REGISTRY;\n    }\n\n    if (Strings.isNullOrEmpty(repository)) {\n      throw new InvalidImageReferenceException(reference);\n    }\n    /*\n     * If a registry was matched but it does not contain any dots or colons, it should actually be\n     * part of the repository unless it is \"localhost\".","sourceCodeStart":87,"sourceCodeEnd":123,"githubUrl":"https://github.com/GoogleContainerTools/jib/blob/fb949e2676afbbd7dd7a1ef61e20251931325654/jib-core/src/main/java/com/google/cloud/tools/jib/api/ImageReference.java#L87-L123","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check the reference string matches docker image syntax: [registry/]repository[:tag][@digest]","Print/log the exact string thrown — the exception message contains the full invalid reference","Ensure variables used to build the reference are non-empty and contain no illegal characters","Catch InvalidImageReferenceException and validate user input before calling jib APIs"],"exampleFix":"// before\nJib.from(imageNameFromConfig); // imageNameFromConfig may be empty\n// after\nif (imageNameFromConfig == null || imageNameFromConfig.isEmpty() || !imageNameFromConfig.matches(\"[a-zA-Z0-9._/-]+(:[a-zA-Z0-9._-]+)?\")) {\n  throw new IllegalArgumentException(\"Invalid image name: \" + imageNameFromConfig);\n}\nJib.from(imageNameFromConfig);","handlingStrategy":"validation","validationCode":"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})?\");","typeGuard":"if (ref == null || ref.isEmpty() || !ref.matches(\"([a-zA-Z0-9.:-]+/)?[a-z0-9._/-]+(:[a-zA-Z0-9._-]+)?\")) return Optional.empty();","tryCatchPattern":"try { return ImageReference.parse(ref); } catch (InvalidImageReferenceException e) { throw new IllegalArgumentException(\"Bad image reference: \" + e.getMessage(), e); }","preventionTips":["Validate image names from user config/CLI before parsing","Never interpolate empty variables into reference strings","Use ImageReference.of(registry, repository, tag) to build references from parts"],"tags":["image-reference","validation","jib"],"backgroundTag":"invalid-argument-format","analyzedSha":"fb949e2676afbbd7dd7a1ef61e20251931325654","analyzedAt":"2026-09-06T14:04:09.491Z","contentChangedAt":"2026-09-06T14:04:09.491Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}