GoogleContainerTools/jib · error · RegistryErrorException

'WWW-Authenticate' header not found

Error message

'WWW-Authenticate' header not found

What it means

Built by AuthenticationMethodRetriever.handleHttpResponseException when the registry responds with an HTTP 401 but the response has no 'WWW-Authenticate' header. Jib needs that header (Bearer/Basic challenge) to learn where to authenticate, so without it the 401 cannot be resolved. It surfaces as RegistryErrorException with this reason.

Source

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

  }

  @Override
  public String getActionDescription() {
    return "retrieve authentication method for " + registryEndpointRequestProperties.getServerUrl();
  }

  @Override
  public Optional<RegistryAuthenticator> handleHttpResponseException(
      ResponseException responseException) throws ResponseException, RegistryErrorException {
    // Only valid for status code of '401 Unauthorized'.
    if (responseException.getStatusCode() != HttpStatusCodes.STATUS_CODE_UNAUTHORIZED) {
      throw responseException;
    }

    // Checks if the 'WWW-Authenticate' header is present.
    String authenticationMethod = responseException.getHeaders().getAuthenticate();
    if (authenticationMethod == null) {
      throw new RegistryErrorExceptionBuilder(getActionDescription(), responseException)
          .addReason("'WWW-Authenticate' header not found")
          .build();
    }

    // Parses the header to retrieve the components.
    try {
      return RegistryAuthenticator.fromAuthenticationMethod(
          authenticationMethod, registryEndpointRequestProperties, userAgent, httpClient);

    } catch (RegistryAuthenticationFailedException ex) {
      throw new RegistryErrorExceptionBuilder(getActionDescription(), ex)
          .addReason("Failed get authentication method from 'WWW-Authenticate' header")
          .build();
    }
  }
}

View on GitHub (pinned to fb949e2676)

Solutions

1. Check whether a proxy, VPN, or gateway is intercepting the registry request and bypass/fix it.
2. Verify the registry hostname/port actually serves a Docker Registry v2 service (curl -v the /v2/ endpoint).
3. Confirm registry server configuration sends the WWW-Authenticate challenge on 401 responses.
4. Run `docker login` against the same registry to see if standard tooling faces the same problem.

// preflight: the /v2/ endpoint must return a WWW-Authenticate challenge
// curl -sv https://registry.example.com/v2/ 2>&1 | grep -i www-authenticate
// a proper registry returns e.g. WWW-Authenticate: Bearer realm="..."

// catch and surface registry auth-challenge problems
try {
    jibContainerBuilder.containerize();
} catch (RegistryErrorException e) {
    if (e.getMessage().contains("WWW-Authenticate")) {
        throw new IllegalStateException("Registry/proxy returned 401 without WWW-Authenticate — check proxy and registry config", e);
    }
    throw e;
}

When it happens

Trigger: A registry (or an intermediary like a load balancer, proxy, or error page) returns 401 without the WWW-Authenticate challenge header during image push/pull.

Common situations: Corporate proxies or API gateways intercepting registry traffic, misconfigured reverse proxies returning bare 401s, or a non-Docker service listening on the registry port.

Understand the failure class

• Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

• Failed get authentication method from 'WWW-Authenticate' hea
• Did not receive Content-Length header
• platform does not support TLS protocol
• insecure HTTP connection not allowed: + url
• Cannot find field 'schemaVersion' in manifest

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