What causes "Expected 1 'Location' header, but found ${headerCount}" in GoogleContainerTools/jib?

Fix or replace the non-compliant registry/proxy so a single Location header is returned with 202 responses

GoogleContainerTools/jib · error · RegistryErrorException

Expected 1 'Location' header, but found ${headerCount}

Error message

Expected 1 'Location' header, but found ${headerCount}

What it means

When the registry responds 202 Accepted to a blob upload, Jib requires exactly one 'Location' header telling it where to continue the upload. If zero or multiple Location headers are present, the registry response violates the expected protocol and Jib throws a RegistryErrorException.

Source

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

  }

  /**
   * Extract the {@code Location} header from the response to get the new location for the next
   * request.
   *
   * <p>The {@code Location} header can be relative or absolute.
   *
   * @see <a
   *     href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Location#Directives">https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Location#Directives</a>
   * @param response the response to extract the 'Location' header from
   * @return the new location for the next request
   * @throws RegistryErrorException if there was not a single 'Location' header
   */
  private URL getRedirectLocation(Response response) throws RegistryErrorException {
    // Extracts and returns the 'Location' header.
    List<String> locationHeaders = response.getHeader("Location");
    if (locationHeaders.size() != 1) {
      throw buildRegistryErrorException(
          "Expected 1 'Location' header, but found " + locationHeaders.size());
    }

    String locationHeader = locationHeaders.get(0);
    return response.getRequestUrl().toURL(locationHeader);
  }
}

View on GitHub (pinned to fb949e2676)

Solutions

Fix or replace the non-compliant registry/proxy so a single Location header is returned with 202 responses
Check intermediary proxies for header manipulation (e.g. duplicate add_header directives)
Retry against the registry directly without a proxy to confirm where the bad response originates
Use a spec-compliant registry (Distribution/registry:2, GCR, ECR, Docker Hub)

Example fix

// nginx proxy before
add_header Location $upstream_http_location;
add_header Location $upstream_http_location;
// after
proxy_pass_header Location;

Defensive patterns

Strategy: validation

Validate before calling

// preflight blob push and inspect Location header
curl -i -X POST https://registry:5000/v2/myapp/blobs/uploads/ | grep -i '^location:'

Try / catch

try {
  jibBuild.push();
} catch (RegistryErrorException e) {
  if (e.getMessage().contains("'Location' header")) {
    System.err.println("Registry/proxy is dropping or duplicating Location headers");
  }
}

Prevention

Ensure proxies use proxy_pass_header / proxy_set_header correctly instead of duplicating add_header
Upgrade old private registry software that omits Location on 202
Verify header behavior with curl before CI pushes

When it happens

Trigger: A registry (or intermediary proxy) responding 202 to a blob push PATCH/PUT with no Location header, or duplicating the Location header.

Common situations: Custom or older private registries that omit Location on 202; reverse proxies that add or duplicate headers; CDN/middleware rewriting upload responses.

Related errors

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