apache/pulsar · error · RuntimeException

You must specify tls-trust-store-type, tls-trust-store and t

Error message

You must specify tls-trust-store-type, tls-trust-store and tls-trust-store-pwd when enable tls-enable-keystore

What it means

validateClusterData checks ClusterData consistency before a cluster is created/updated. When TLS with keystores is enabled for broker client connections (tls-enable-keystore) the trust-store type, path, and password must all be provided; a RuntimeException is thrown when any of the three is blank. Keystore-based TLS cannot be set up without a complete trust store configuration.

Source

Thrown at pulsar-client-tools/src/main/java/org/apache/pulsar/admin/cli/CmdClusters.java:90

    @Command(description = "Provisions a new cluster. This operation requires Pulsar super-user privileges")
    private class Create extends CliCommand {
        @ArgGroup(exclusive = false)
        ClusterDetails clusterDetails = new ClusterDetails();

        @Override
        void run() throws PulsarAdminException, IOException {
            getAdmin().clusters().createCluster(clusterDetails.clusterName, clusterDetails.getClusterData());
        }

    }

    protected static void validateClusterData(ClusterData clusterData) {
        if (clusterData.isBrokerClientTlsEnabled()) {
            if (clusterData.isBrokerClientTlsEnabledWithKeyStore()) {
                if (StringUtils.isAnyBlank(clusterData.getBrokerClientTlsTrustStoreType(),
                        clusterData.getBrokerClientTlsTrustStore(),
                        clusterData.getBrokerClientTlsTrustStorePassword())) {
                    throw new RuntimeException(
                            "You must specify tls-trust-store-type, tls-trust-store and tls-trust-store-pwd"
                                    + " when enable tls-enable-keystore");
                }
            }
        }
    }

    @Command(description = "Update the configuration for a cluster")
    private class Update extends CliCommand {
        @ArgGroup(exclusive = false)
        ClusterDetails clusterDetails = new ClusterDetails();

        @Override
        void run() throws PulsarAdminException, IOException {
            getAdmin().clusters().updateCluster(clusterDetails.clusterName, clusterDetails.getClusterData());
        }

    }

View on GitHub (pinned to 820761864e)

Solutions

Provide all three options together: --tls-trust-store-type, --tls-trust-store, --tls-trust-store-pwd.
If keystore TLS is not needed, remove --tls-enable-keystore so the validation is skipped.
Set the same values persistently in the cluster data via the admin API (ClusterData brokerClientTlsTrustStore* fields).

Example fix

// before
pulsar-admin clusters update c1 --tls-enable-keystore --tls-trust-store /path/truststore.jks
// after
pulsar-admin clusters update c1 --tls-enable-keystore --tls-trust-store-type JKS --tls-trust-store /path/truststore.jks --tls-trust-store-pwd secret

Defensive patterns

Strategy: validation

Validate before calling

if (clusterData.isBrokerClientTlsEnabled() && clusterData.isBrokerClientTlsEnabledWithKeyStore()) {
    boolean anyBlank = Stream.of(clusterData.getBrokerClientTlsTrustStoreType(),
            clusterData.getBrokerClientTlsTrustStore(),
            clusterData.getBrokerClientTlsTrustStorePassword()).anyMatch(StringUtils::isBlank);
    if (anyBlank) throw new IllegalArgumentException("tls-trust-store-type, tls-trust-store and tls-trust-store-pwd are all required with keystore TLS");
}

Try / catch

try {
    admin.clusters().updateCluster(clusterData);
} catch (RuntimeException e) {
    if (e.getMessage().contains("tls-trust-store")) {
        System.err.println("Complete the keystore TLS config: type, store path and password are all required.");
    }
}

Prevention

Treat the three trust-store options as one atomic group whenever --tls-enable-keystore is used.
Keep keystore TLS settings in a config file/template so they are set together.
Never commit the trust-store password; supply it from a secret at deploy time.

When it happens

Trigger: Running 'pulsar-admin clusters create/update' with --tls-enable-keystore (brokerClientTlsEnabledWithKeyStore=true) while omitting --tls-trust-store-type, --tls-trust-store, or --tls-trust-store-pwd (any one blank triggers it).

Common situations: Partially migrating a cluster config from certificate-based to keystore-based TLS and forgetting the password, or copying example commands that only set the trust store path.

Understand the failure class

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

Related errors

AI-assisted analysis of apache/pulsar@820761864e (2026-09-06). Data as JSON: /api/errors/90c42eb7d77c16a8. Report an issue: GitHub.