GoogleContainerTools/jib · error · RegistryErrorException

Received unrecognized status code ${statusCode}

Error message

Received unrecognized status code ${statusCode}

What it means

During blob (layer) push, after sending the blob Jib expects either 201 Created (already exists), 202 with a Location header (resume/redirect), or 204. Any other status code is unexpected for the registry protocol and Jib throws a RegistryErrorException via buildRegistryErrorException.

Source

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

      return Collections.emptyList();
    }

    /**
     * Returns a URL to continue pushing the BLOB to, or {@link Optional#empty()} if the BLOB
     * already exists on the registry.
     */
    @Override
    public Optional<URL> handleResponse(Response response) throws RegistryErrorException {
      switch (response.getStatusCode()) {
        case HttpURLConnection.HTTP_CREATED:
          // The BLOB exists in the registry.
          return Optional.empty();

        case HttpURLConnection.HTTP_ACCEPTED:
          return Optional.of(getRedirectLocation(response));

        default:
          throw buildRegistryErrorException(
              "Received unrecognized status code " + response.getStatusCode());
      }
    }

    @Override
    public URL getApiRoute(String apiRouteBase) throws MalformedURLException {
      StringBuilder url =
          new StringBuilder(apiRouteBase)
              .append(registryEndpointRequestProperties.getImageName())
              .append("/blobs/uploads/");
      if (sourceRepository != null) {
        url.append("?mount=").append(blobDigest).append("&from=").append(sourceRepository);
      }

      return new URL(url.toString());
    }

    @Override

View on GitHub (pinned to fb949e2676)

Solutions

1. Check the registry server logs for the root cause of the unexpected status
2. Verify the registry is a spec-compliant Docker Registry v2 implementation
3. Bypass intermediate proxies that may rewrite upload responses
4. Retry the push; if persistent, test against a known-good registry (Docker Hub, GCR) to isolate the registry's behavior

// preflight: check registry reachability and API version
curl -fsS https://registry:5000/v2/ || echo "registry not v2-compliant"

try {
  jibBuild.push();
} catch (RegistryErrorException e) {
  if (e.getMessage().contains("unrecognized status code")) {
    // retry once, else fail with registry diagnostics
    retryPushOrReportRegistryLogs(e);
  }
}

When it happens

Trigger: The registry returns an unexpected status code (anything other than 201, 202, or 204) in response to the PATCH/PUT blob-upload requests during image push.

Common situations: Non-standard or buggy private registry implementations; proxies or load balancers injecting 4xx/5xx responses mid-upload; registry rejecting the blob for quota or policy reasons with an unusual status.

Related errors

• ${helpfulSuggestions.forHttpStatusCodeForbidden(registryUnau
• Expected 1 'Location' header, but found ${headerCount}
• Tried to ${actionDescription} but failed because: ${registry
• Failed to authenticate with registry ${registryUrl}/${imageN
• push may fail with pull-only bearer auth token

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