grpc/grpc-java · error · RuntimeException

Failed to build SSL context from certificate streams: ${e}

Error message

Failed to build SSL context from certificate streams: ${e}

What it means

The InputStream overload of useTransportSecurity(certChain, privateKey) builds a server SslContext with GrpcSslContexts.forServer(certChain, privateKey).build(). SSLException from that build is wrapped in a RuntimeException with message "Failed to build SSL context from certificate streams" (original SSLException as cause).

Source

Thrown at netty/src/main/java/io/grpc/netty/NettyServerBuilder.java:839

    } catch (SSLException e) {
      // This should likely be some other, easier to catch exception.
      throw new RuntimeException(e);
    }
    protocolNegotiatorFactory = ProtocolNegotiators.serverTlsFactory(sslContext);
    return this;
  }

  @CanIgnoreReturnValue
  @Override
  public NettyServerBuilder useTransportSecurity(InputStream certChain, InputStream privateKey) {
    checkState(!freezeProtocolNegotiatorFactory,
               "Cannot change security when using ServerCredentials");
    SslContext sslContext;
    try {
      sslContext = GrpcSslContexts.forServer(certChain, privateKey).build();
    } catch (SSLException e) {
      // This should likely be some other, easier to catch exception.
      throw new RuntimeException(e);
    }
    protocolNegotiatorFactory = ProtocolNegotiators.serverTlsFactory(sslContext);
    return this;
  }
}

View on GitHub (pinned to 64daddc1f3)

Solutions

1. Inspect the cause SSLException for the exact parsing error.
2. Ensure streams are fresh (not yet consumed) and contain PEM data; reopen resources per call.
3. Decrypt password-protected keys beforehand or supply unencrypted PEM keys.
4. Validate material offline with `openssl x509 -in cert.pem` and `openssl pkey -in key.pem` before shipping.

Example fix

// before
InputStream cert = getClass().getResourceAsStream("/certs/server.crt"); // may be null/empty
serverBuilder.useTransportSecurity(cert, key);
// after
try (InputStream cert = requireNonNull(getClass().getResourceAsStream("/certs/server.pem"));
     InputStream key = requireNonNull(getClass().getResourceAsStream("/certs/server-key.pem"))) {
  serverBuilder.useTransportSecurity(cert, key);
}

byte[] certBytes = readAll(certStream); // stream must not be consumed/empty
if (certBytes.length == 0) throw new IllegalArgumentException("empty cert chain stream");
if (!new String(certBytes, UTF_8).startsWith("-----BEGIN CERTIFICATE")) throw new IllegalArgumentException("not PEM");

try {
  serverBuilder.useTransportSecurity(certStream, keyStream);
} catch (RuntimeException e) {
  if (e.getCause() instanceof SSLException) {
    // reopen fresh streams and verify PEM contents
  }
}

When it happens

Trigger: Calling useTransportSecurity(InputStream, InputStream) with streams whose contents are not a valid PEM X.509 cert chain plus unencrypted PEM private key — empty streams, wrong formats, encrypted keys, or streams already consumed (positioned at EOF).

Common situations: Loading cert material from the classpath where the resource was missing/empty; passing an encrypted key without a password; reusing an InputStream already read by another component; DER-encoded material passed as PEM.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

• SSL/TLS and certificate errors — how TLS handshakes and certificate validation fail.

Related errors

• Failed to build SSL context from certificate files: ${e}
• Unexpected error converting ChannelCredentials to Netty SslC
• Unexpected error converting ServerCredentials to Netty SslCo
• Can't set TLS settings for ALTS
• TLS Provider failure

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