GoogleContainerTools/jib · error · RegistryErrorException

Tried to ${actionDescription} but failed because: ${registry

Error message

Tried to ${actionDescription} but failed because: ${registryErrorReasons}

What it means

Jib wraps registry HTTP response exceptions into a RegistryErrorException. For 400, 404, and 405 responses it concludes the image name or reference (tag/digest) was invalid, and the thrown error aggregates the attempted action description with all underlying registry error reasons from the response body.

Source

Thrown at jib-core/src/main/java/com/google/cloud/tools/jib/registry/RegistryEndpointCaller.java:153

            .setAuthorization(authorization);

    try (Response response =
        httpClient.call(registryEndpointProvider.getHttpMethod(), url, requestBuilder.build())) {

      return registryEndpointProvider.handleResponse(response);

    } catch (ResponseException ex) {
      // First, see if the endpoint provider handles an exception as an expected response.
      try {
        return registryEndpointProvider.handleHttpResponseException(ex);

      } catch (ResponseException responseException) {
        if (responseException.getStatusCode() == HttpStatusCodes.STATUS_CODE_BAD_REQUEST
            || responseException.getStatusCode() == HttpStatusCodes.STATUS_CODE_NOT_FOUND
            || responseException.getStatusCode()
                == HttpStatusCodes.STATUS_CODE_METHOD_NOT_ALLOWED) {
          // The name or reference was invalid.
          throw newRegistryErrorException(responseException);

        } else if (responseException.getStatusCode() == HttpStatusCodes.STATUS_CODE_FORBIDDEN) {
          throw new RegistryUnauthorizedException(serverUrl, imageName, responseException);

        } else if (responseException.getStatusCode() == HttpStatusCodes.STATUS_CODE_UNAUTHORIZED) {
          if (responseException.requestAuthorizationCleared()) {
            throw new RegistryCredentialsNotSentException(serverUrl, imageName);
          } else {
            // Credentials are either missing or wrong.
            throw new RegistryUnauthorizedException(serverUrl, imageName, responseException);
          }

        } else {
          // Unknown
          throw responseException;
        }
      }

View on GitHub (pinned to fb949e2676)

Solutions

Verify the image reference (registry/repository:tag) is spelled correctly and exists (check with docker pull or the registry UI)
Check tag/digest casing and allowed characters for the registry
Confirm the repository exists and your account has pull/push access
Inspect the included registryErrorReasons in the message for the registry's own explanation

Example fix

// before
mvn jib:build -Dimage=myregistry.io/my-Project:Latest
// after
mvn jib:build -Dimage=myregistry.io/my-project:latest

Defensive patterns

Strategy: try-catch

Validate before calling

// validate the reference locally before building
if (!imageRef.matches("[a-z0-9]+(\.[a-z0-9]+)*(:\d+)?/[a-z0-9._/-]+(:[a-zA-Z0-9._-]+)?")) {
  throw new IllegalArgumentException("Invalid image reference: " + imageRef);
}

Type guard

boolean isValidImageRef(String ref) {
  return ref != null && ref.matches("[a-z0-9]+([._-][a-z0-9]+)*(:\d+)?(/[a-z0-9._/-]+)+(:[\w.-]+)?");
}

Try / catch

try {
  jibBuild.containerize(...);
} catch (RegistryErrorException e) {
  // message contains action + aggregated registryErrorReasons
  System.err.println("Image/reference rejected by registry: " + e.getMessage());
  verifyImageNameAndTag(e);
}

Prevention

Verify the image tag exists with docker pull before CI builds
Use lowercase repository names and valid tag characters
Confirm registry permissions for the account doing pull/push
Log the full RegistryErrorException message; it embeds the registry's own reasons

When it happens

Trigger: Any registry endpoint call (manifest pull/push, blob operations) that receives a 400 Bad Request, 404 Not Found, or 405 Method Not Allowed response.

Common situations: Typo in image name, repository, or tag; referencing a tag/digest that does not exist; pushing to a repository path the registry rejects as invalid; registry not supporting a requested operation.

Understand the failure class

Background: "API error: {status}" and "HTTP 401/403/404/429/5xx" errors: non-2xx HTTP responses explained — this error's family across 27 libraries.

Related errors

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