What causes "trustCollectionCertFile must be not null" in alibaba/nacos?

Set tlsConfig.setTrustCollectionCertFile() to a valid PEM file path (or a classpath: URL the ResourceLoader can resolve).

alibaba/nacos · error · IllegalArgumentException

trustCollectionCertFile must be not null

Error message

trustCollectionCertFile must be not null

What it means

GrpcClient.buildSslContext() requires a trust store when trustAll is disabled: with trustAll=false it must load `trustCollectionCertFile` to verify the server. If that field is blank, it throws IllegalArgumentException before attempting to load the trust material.

Source

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

            return Optional.empty();
        }
        try {
            SslContextBuilder builder = GrpcSslContexts.forClient();
            if (StringUtils.isNotBlank(tlsConfig.getSslProvider())) {
                builder.sslProvider(TlsTypeResolve.getSslProvider(tlsConfig.getSslProvider()));
            }
            
            if (StringUtils.isNotBlank(tlsConfig.getProtocols())) {
                builder.protocols(tlsConfig.getProtocols().split(","));
            }
            if (StringUtils.isNotBlank(tlsConfig.getCiphers())) {
                builder.ciphers(Arrays.asList(tlsConfig.getCiphers().split(",")));
            }
            if (tlsConfig.getTrustAll()) {
                builder.trustManager(InsecureTrustManagerFactory.INSTANCE);
            } else {
                if (StringUtils.isBlank(tlsConfig.getTrustCollectionCertFile())) {
                    throw new IllegalArgumentException("trustCollectionCertFile must be not null");
                }
                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());

View on GitHub (pinned to 9b989acdf1)

Solutions

Set tlsConfig.setTrustCollectionCertFile() to a valid PEM file path (or a classpath: URL the ResourceLoader can resolve).
Alternatively, set tlsConfig.setTrustAll(true) for development only when you cannot supply a CA file.
Double-check the YAML/property key name matches the setter exactly.
Verify the file is readable by the process (permissions, path).

Example fix

// before — TLS on, trustAll off, no CA file
RpcClientTlsConfig tls = new RpcClientTlsConfig();
tls.setEnableTls(true);

// after — supply trust collection
RpcClientTlsConfig tls = new RpcClientTlsConfig();
tls.setEnableTls(true);
tls.setTrustCollectionCertFile("/etc/nacos/certs/ca.pem");

Defensive patterns

Strategy: validation

Validate before calling

static void validateTls(RpcClientTlsConfig tls) {
    if (tls.getEnableTls() != null && tls.getEnableTls() && !Boolean.TRUE.equals(tls.getTrustAll())) {
        if (tls.getTrustCollectionCertFile() == null || tls.getTrustCollectionCertFile().isBlank()) {
            throw new IllegalArgumentException(
                "TLS enabled without trustAll: must set trustCollectionCertFile");
        }
    }
}

Try / catch

try {
    client.start();
} catch (RuntimeException re) {
    if (re.getMessage().contains("trustCollectionCertFile")) {
        // set the CA file or enable trustAll, then retry
    } else { throw re; }
}

Prevention

Validate TLS config before client.start() — trustAll=false requires a CA file.
Keep a checklist of required TLS fields for each mode (one-way vs mTLS).
Use a config validator in tests to catch blank TLS fields at build time.

When it happens

Trigger: Constructing an RpcClientTlsConfig with enableTls=true and trustAll=false (or unset, defaulting false), then starting the client so buildSslContext() runs. The blank check on getTrustCollectionCertFile() fails.

Common situations: Enabling TLS but forgetting to point to the CA trust-collection PEM; pointing to a system property that resolved to empty; YAML key typo (e.g. trustCollectionCertFile vs trustCollectionCert) leaving the field null; assuming a default trust store exists (none does in this builder path).

Related errors

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