grpc/grpc-java · error · CertificateParsingException

Invalid SAN entry: null altNameType

Error message

Invalid SAN entry: null altNameType

What it means

After the structural check, verifyOneSanInList casts entry.get(0) to Integer (the SAN type) and requires it to be non-null before switching on ALT_DNS_NAME / ALT_URI_NAME / ALT_IPA_NAME. If the first element is null, it throws CertificateParsingException('Invalid SAN entry: null altNameType'), meaning the parsed SAN entry lacks a usable type discriminator.

Source

Thrown at xds/src/main/java/io/grpc/xds/internal/security/trust/XdsX509TrustManager.java:184

  private static boolean verifyDnsNameInSanList(
      String altNameFromCert, List<StringMatcher> verifySanList) {
    for (StringMatcher verifySan : verifySanList) {
      if (verifyDnsNameInPattern(altNameFromCert, verifySan)) {
        return true;
      }
    }
    return false;
  }

  private static boolean verifyOneSanInList(List<?> entry, List<StringMatcher> verifySanList)
      throws CertificateParsingException {
    // from OkHostnameVerifier.getSubjectAltNames
    if (entry == null || entry.size() < 2) {
      throw new CertificateParsingException("Invalid SAN entry");
    }
    Integer altNameType = (Integer) entry.get(0);
    if (altNameType == null) {
      throw new CertificateParsingException("Invalid SAN entry: null altNameType");
    }
    switch (altNameType) {
      case ALT_DNS_NAME:
      case ALT_URI_NAME:
      case ALT_IPA_NAME:
        return verifyDnsNameInSanList((String) entry.get(1), verifySanList);
      default:
        return false;
    }
  }

  // logic from Envoy::Extensions::TransportSockets::Tls::ContextImpl::verifySubjectAltName
  private static void verifySubjectAltNameInLeaf(
      X509Certificate cert, List<StringMatcher> verifyList) throws CertificateException {
    Collection<List<?>> names = cert.getSubjectAlternativeNames();
    if (names == null || names.isEmpty()) {
      throw new CertificateException("Peer certificate SAN check failed");
    }

View on GitHub (pinned to 64daddc1f3)

Solutions

1. Replace the certificate with one whose SAN extension is well-formed (verify with openssl x509 -text)
2. Switch or update the security provider responsible for parsing the certificate (e.g. conscrypt/BouncyCastle version bump)
3. Catch CertificateParsingException during verification and treat the cert as untrusted rather than crashing
4. If parsing your own cert collections, ensure each entry is a non-null [Integer type, String value] pair

Example fix

// before: manual SAN list entries like Arrays.asList(null, "foo.example.com")
List<?> entry = Arrays.asList(null, "foo.example.com");
// after
List<?> entry = Arrays.asList(2 /* ALT_DNS_NAME */, "foo.example.com");

// Ensure SAN entry type is a non-null Integer before switching
boolean sanTypeKnown(List<?> entry) {
  return entry != null && entry.size() >= 2 && entry.get(0) instanceof Integer
      && entry.get(0) != null;
}

static boolean hasSanType(List<?> entry) {
  return entry != null && entry.size() >= 2 && entry.get(0) instanceof Integer && entry.get(0) != null;
}

try {
  verifySubjectAltNameInLeaf(certificate, sanList);
} catch (CertificateParsingException e) {
  if (e.getMessage() != null && e.getMessage().contains("null altNameType")) {
    logger.error("SAN entry missing type; check certificate/provider parser", e);
  }
  throw e;
}

When it happens

Trigger: Same path as the malformed-SAN case: certificate.getSubjectAlternativeNames() yields an entry whose first element is null — typically from a non-conforming security provider's parser or a corrupted/oddly encoded SAN extension.

Common situations: Custom or buggy X509Certificate implementations; certificates with empty/unparsable GeneralName entries; provider version bugs decoding SAN extensions into lists with null first elements.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• Invalid SAN entry
• match_subject_alt_names only allowed in upstream_tls_context
• Multiple URI SAN values found in the leaf cert.
• Failed to find X509ExtendedTrustManager with default TrustMa
• Want certificate verification but got null or empty certific

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