alibaba/nacos · error · RuntimeException

Unable to build SslContext

Error message

Unable to build SslContext

What it means

GrpcClient.buildSslContext() wraps any exception during SSL context construction (loading trust/key material, Netty SslContextBuilder.build(), unsupported protocol/cipher) in a RuntimeException 'Unable to build SslContext'. It is the catch-all for the whole TLS setup block, including the two IllegalArgumentExceptions (776, 777) when they escape, plus IO/parse failures on the PEM files.

Source

Thrown at common/src/main/java/com/alibaba/nacos/common/remote/client/grpc/GrpcClient.java:592

                Resource resource =
                    resourceLoader.getResource(tlsConfig.getTrustCollectionCertFile());
                builder.trustManager(resource.getInputStream());
            }
            
            if (tlsConfig.getMutualAuthEnable()) {
                if (StringUtils.isBlank(tlsConfig.getCertChainFile()) || StringUtils.isBlank(
                    tlsConfig.getCertPrivateKey())) {
                    throw new IllegalArgumentException(
                        "client certChainFile or certPrivateKey must be not null");
                }
                Resource certChainFile = resourceLoader.getResource(tlsConfig.getCertChainFile());
                Resource privateKey = resourceLoader.getResource(tlsConfig.getCertPrivateKey());
                builder.keyManager(certChainFile.getInputStream(), privateKey.getInputStream(),
                    tlsConfig.getCertPrivateKeyPassword());
            }
            return Optional.of(builder.build());
        } catch (Exception e) {
            throw new RuntimeException("Unable to build SslContext", e);
        }
    }
    
    private ManagedChannelBuilder buildChannel(String serverIp, int port,
        Optional<SslContext> sslContext) {
        if (sslContext.isPresent()) {
            return NettyChannelBuilder.forAddress(serverIp, port)
                .negotiationType(NegotiationType.TLS)
                .sslContext(sslContext.get());
            
        } else {
            return ManagedChannelBuilder.forAddress(serverIp, port).usePlaintext();
        }
    }
    
    /**
     * Setup response handler.
     */

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Read the wrapped cause (`e` in the catch) — it states the exact failure (FileNotFound, malformed PEM, unsupported cipher).
2. Confirm all referenced PEM files exist, are readable, and are in a supported format (PKCS#8 private key, PEM-encoded chain).
3. Validate the protocols/ciphers lists against what the runtime SSL provider supports; remove unsupported entries.
4. If a key is encrypted, supply the correct password via setCertPrivateKeyPassword().
5. Ensure the correct SSL provider JARs are on the classpath (netty-tcnative / Conscrypt) if you require specific protocols.

static void validateTlsFilesReadable(RpcClientTlsConfig tls, ResourceLoader loader) throws IOException {
    if (!isBlank(tls.getTrustCollectionCertFile()))
        try (InputStream ignored = loader.getResource(tls.getTrustCollectionCertFile()).getInputStream()) {}
    if (!isBlank(tls.getCertChainFile()))
        try (InputStream ignored = loader.getResource(tls.getCertChainFile()).getInputStream()) {}
    if (!isBlank(tls.getCertPrivateKey()))
        try (InputStream ignored = loader.getResource(tls.getCertPrivateKey()).getInputStream()) {}
}

try {
    client.start();
} catch (RuntimeException re) {
    if ("Unable to build SslContext".equals(re.getMessage())) {
        Throwable cause = re.getCause(); // real reason: IO, malformed PEM, bad cipher
        // fix cause, then retry
    } else { throw re; }
}

When it happens

Trigger: Any failure inside the try block of buildSslContext: unreadable cert/key files, malformed PEM, unsupported protocol specified, unsupported cipher, password mismatch on an encrypted key, or an error from Netty's SslContextBuilder.build().

Common situations: Cert/key file path wrong or unreadable; PEM format mismatch (PKCS#8 vs PKCS#1); protocols/ciphers list contains a value the OpenSSL/JDK provider rejects; private key password incorrect; provider (Conscrypt/OpenSSL) not on classpath; the underlying cause is chained in `e`.

Related errors

• trustCollectionCertFile must be not null
• client certChainFile or certPrivateKey must be not null
• PARAMETER_MISSING
• MCP_SERVER_NOT_FOUND
• MCP_SERVER_REF_ENDPOINT_SERVICE_NOT_FOUND

AI-assisted analysis of alibaba/nacos@9b989acdf1 (2026-08-14). Data as JSON: /api/errors/111de496d46e2e9b. Report an issue: GitHub.