{"record":{"id":"1b480654b34e504e","repo":"grpc/grpc-java","slug":"failed-to-build-ssl-context-from-certificate-files","errorCode":null,"errorMessage":"Failed to build SSL context from certificate files: ${e}","messagePattern":"Failed to build SSL context from certificate files: (.+?)","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"netty/src/main/java/io/grpc/netty/NettyServerBuilder.java","lineNumber":823,"sourceCode":"  }\n\n  @CanIgnoreReturnValue\n  NettyServerBuilder setTransportTracerFactory(TransportTracer.Factory transportTracerFactory) {\n    this.transportTracerFactory = transportTracerFactory;\n    return this;\n  }\n\n  @CanIgnoreReturnValue\n  @Override\n  public NettyServerBuilder useTransportSecurity(File certChain, File privateKey) {\n    checkState(!freezeProtocolNegotiatorFactory,\n               \"Cannot change security when using ServerCredentials\");\n    SslContext sslContext;\n    try {\n      sslContext = GrpcSslContexts.forServer(certChain, privateKey).build();\n    } catch (SSLException e) {\n      // This should likely be some other, easier to catch exception.\n      throw new RuntimeException(e);\n    }\n    protocolNegotiatorFactory = ProtocolNegotiators.serverTlsFactory(sslContext);\n    return this;\n  }\n\n  @CanIgnoreReturnValue\n  @Override\n  public NettyServerBuilder useTransportSecurity(InputStream certChain, InputStream privateKey) {\n    checkState(!freezeProtocolNegotiatorFactory,\n               \"Cannot change security when using ServerCredentials\");\n    SslContext sslContext;\n    try {\n      sslContext = GrpcSslContexts.forServer(certChain, privateKey).build();\n    } catch (SSLException e) {\n      // This should likely be some other, easier to catch exception.\n      throw new RuntimeException(e);\n    }\n    protocolNegotiatorFactory = ProtocolNegotiators.serverTlsFactory(sslContext);","sourceCodeStart":805,"sourceCodeEnd":841,"githubUrl":"https://github.com/grpc/grpc-java/blob/64daddc1f3d1975670f769f3e97bde8b2ba32d25/netty/src/main/java/io/grpc/netty/NettyServerBuilder.java#L805-L841","documentation":"useTransportSecurity(File certChain, File privateKey) builds a server SslContext with GrpcSslContexts.forServer(certChain, privateKey).build(). If that build throws SSLException, it is wrapped in a RuntimeException with message \"Failed to build SSL context from certificate files\" (original SSLException as cause).","triggerScenarios":"Calling useTransportSecurity(File, File) where the certificate chain or private key file is malformed, in an unsupported format (e.g. PKCS#12 or encrypted key passed where unencrypted PEM is required), or unreadable such that GrpcSslContexts cannot parse them into an SslContext.","commonSituations":"Pointing at a full-chain bundle or a certificate in the wrong format; using an encrypted/private-key-protected PEM without a password; mixing DER and PEM; corrupted or truncated certificate files; missing netty-tcnative causing provider errors.","solutions":["Inspect the cause SSLException for the parsing failure detail.","Provide an unencrypted PEM private key and a PEM X.509 certificate chain.","Use the stream variant and pre-validate: pass FileInputStream/InputStreams you have confirmed parse (e.g. via openssl x509 / openssl pkey).","Prefer TlsServerCredentials / ServerCredentials (forAddress with credentials) which reports conversion problems as IllegalArgumentException with clearer messages."],"exampleFix":"// before\nserverBuilder.useTransportSecurity(new File(\"server.p12\"), new File(\"server.key\")); // wrong formats\n// after\nserverBuilder.useTransportSecurity(new File(\"server.pem\"), new File(\"server-key.pem\")); // unencrypted PEM","handlingStrategy":"validation","validationCode":"// Pre-validate PEM material before calling useTransportSecurity\nString cert = Files.readString(certChainFile);\nString key = Files.readString(privateKeyFile);\nif (!cert.startsWith(\"-----BEGIN CERTIFICATE\")) throw new IllegalArgumentException(\"cert is not PEM\");\nif (!key.startsWith(\"-----BEGIN\")) throw new IllegalArgumentException(\"key is not PEM\");\nif (key.contains(\"ENCRYPTED\")) throw new IllegalArgumentException(\"key must be unencrypted\");","typeGuard":null,"tryCatchPattern":"try {\n  serverBuilder.useTransportSecurity(certChain, privateKey);\n} catch (RuntimeException e) {\n  if (e.getCause() instanceof SSLException) {\n    // bad cert/key files: check format, encryption, pairing\n  }\n}","preventionTips":["Use unencrypted PEM key and PEM X.509 chain only","Validate with openssl x509 / openssl pkey before deploying","Confirm cert chain and key are a matching pair"],"tags":["grpc","java","tls","ssl-context","certificates"],"backgroundTag":"file-read-failed","analyzedSha":"64daddc1f3d1975670f769f3e97bde8b2ba32d25","analyzedAt":"2026-09-08T06:14:57.704Z","contentChangedAt":"2026-09-08T06:14:57.704Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}