grpc/grpc-java · error · IllegalStateException

checkServerTrustedMethod not found

Error message

checkServerTrustedMethod not found

What it means

X509AuthorityVerifier verifies that the certificate authority presented by the peer is acceptable by reflectively invoking checkServerTrusted(X509Certificate[], String, SSLEngine) on an X509ExtendedTrustManager. If that method handle was never resolved (null), an IllegalStateException is thrown before invocation. This is an internal invariant: the trust manager should have provided the method during initialization.

Source

Thrown at netty/src/main/java/io/grpc/netty/X509AuthorityVerifier.java:103

    if (portNumberSeperatorColonIndex > closingSquareBracketIndex) {
      return authority.substring(0, portNumberSeperatorColonIndex);
    }
    return authority;
  }

  private void verifyAuthorityAllowedForPeerCert(String authority)
          throws SSLPeerUnverifiedException, CertificateException, InvocationTargetException,
          IllegalAccessException {
    SSLEngine sslEngineWrapper = new ProtocolNegotiators.SslEngineWrapper(sslEngine, authority);
    // The typecasting of Certificate to X509Certificate should work because this method will only
    // be called when using TLS and thus X509.
    Certificate[] peerCertificates = sslEngine.getSession().getPeerCertificates();
    X509Certificate[] x509PeerCertificates = new X509Certificate[peerCertificates.length];
    for (int i = 0; i < peerCertificates.length; i++) {
      x509PeerCertificates[i] = (X509Certificate) peerCertificates[i];
    }
    if (checkServerTrustedMethod == null) {
      throw new IllegalStateException("checkServerTrustedMethod not found");
    }
    checkServerTrustedMethod.invoke(
            x509ExtendedTrustManager, x509PeerCertificates, "UNKNOWN", sslEngineWrapper);
  }
}

View on GitHub (pinned to 64daddc1f3)

Solutions

1. Use a standard JDK/Conscrypt trust manager setup and a supported JVM version (JDK 8+)
2. Check how checkServerTrustedMethod is resolved in X509AuthorityVerifier and ensure the default TrustManagerFactory (not a bare X509TrustManager) supplies the extended trust manager
3. Upgrade grpc-netty to a version with fixes to X509 authority verification
4. Remove conflicting security providers/agents that hide X509ExtendedTrustManager

try {
  channel = builder.build();
} catch (IllegalStateException e) {
  if (e.getMessage() != null && e.getMessage().contains("checkServerTrustedMethod not found")) {
    throw new IllegalStateException("TLS trust-manager reflection unsupported on this JVM/provider: " + e, e);
  }
  throw e;
}

When it happens

Trigger: verifyAuthority -> verifyAuthorityAllowedForPeerCert runs during a TLS handshake with custom trust managers when the reflective lookup of checkServerTrusted failed at class init (unusual JVM, non-standard X509ExtendedTrustManager, or overridden security provider).

Common situations: Custom security providers or FIPS JVMs where X509ExtendedTrustManager resolution differs; instrumentation/agents interfering with reflection; running on a JVM where the assumed trust-manager API surface isn't present.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• SocketFactory ${socketFactory} did not produce an SSLSocket:
• Expected NPN/ALPN ${expectedProtocol}: ${negotiatedProtocol}
• Can't set TLS settings for ALTS
• Could not get enough key data from the handshake.
• Handshaker service error: ${status.getDetails()}

AI-assisted analysis of grpc/grpc-java@64daddc1f3 (2026-09-08). Data as JSON: /api/errors/9cb83e8077943ae8. Report an issue: GitHub.