What causes "Could not configure MongoDB client with TLS registry" in quarkusio/quarkus?

Check the wrapped cause `e` in the exception stack trace — it names the real keystore/SSL failure

quarkusio/quarkus · error · MongoConfigurationException

Could not configure MongoDB client with TLS registry

Error message

Could not configure MongoDB client with TLS registry

What it means

When a TLS registry is configured for the MongoDB client, Quarkus builds an SSLContext from it via tlsConfig.createSSLContext(). If that construction throws, the failure is wrapped in a MongoConfigurationException with this message.

Source

Thrown at extensions/mongodb-client/runtime/src/main/java/io/quarkus/mongodb/runtime/MongoClients.java:275

            this.tlsConfigurationRegistry = tlsConfigurationRegistry;
        }

        @Override
        public void apply(SslSettings.Builder builder) {
            builder.enabled(!disableSslSupport);
            if (!disableSslSupport) {
                Optional<TlsConfiguration> tlsConfig = TlsConfiguration.from(tlsConfigurationRegistry,
                        config.tlsConfigurationName());
                if (tlsConfig.isPresent()) {
                    // Honor the hostname verification configured at the TLS registry level.
                    // "NONE" disables hostname verification, which maps to allowing invalid host names.
                    boolean insecure = tlsConfig.get().getHostnameVerificationAlgorithm()
                            .map("NONE"::equals).orElse(false);
                    builder.invalidHostNameAllowed(insecure);
                    try {
                        builder.context(tlsConfig.get().createSSLContext());
                    } catch (Exception e) {
                        throw new MongoConfigurationException("Could not configure MongoDB client with TLS registry", e);
                    }
                } else {
                    builder.invalidHostNameAllowed(false);
                }
            }
        }
    }

    private static class SocketSettingsBuilder implements Block<SocketSettings.Builder> {
        public SocketSettingsBuilder(MongoClientConfig config) {
            this.config = config;
        }

        private final MongoClientConfig config;

        @Override
        public void apply(SocketSettings.Builder builder) {
            if (config.connectTimeout().isPresent()) {

View on GitHub (pinned to e1c734241f)

Solutions

Check the wrapped cause `e` in the exception stack trace — it names the real keystore/SSL failure
Verify keystore/truststore file paths exist at runtime and are readable (include them in the container image)
Confirm keystore type and password match (`quarkus.mongodb.tls-configuration-name` and the referenced quarkus.tls.* config)
Test the TLS registry config with another component to isolate whether the problem is the registry or the Mongo wiring

Example fix

// before
quarkus.mongodb.tls-configuration-name=mongo-tls
quarkus.tls.mongo-tls.key-store.p12.path=/etc/certs/wrong.p12
// after
quarkus.mongodb.tls-configuration-name=mongo-tls
quarkus.tls.mongo-tls.key-store.p12.path=/etc/certs/server.p12
quarkus.tls.mongo-tls.key-store.p12.password=${KEYSTORE_PASSWORD}

Defensive patterns

Strategy: validation

Validate before calling

// Verify the keystore is loadable before startup
try (var in = new FileInputStream(tlsKeystorePath)) {
    KeyStore.getInstance(tlsKeystoreType).load(in, password.toCharArray());
} catch (Exception e) {
    throw new IllegalStateException("TLS keystore invalid: " + e.getMessage(), e);
}

Try / catch

try {
    mongoClient = mongoClients.create(name);
} catch (MongoConfigurationException e) {
    throw new StartupException("Mongo TLS setup failed, check TLS registry config", e.getCause());
}

Prevention

Mount certificates into the container image and verify paths exist at startup
Keep keystore passwords in config expressions bound to environment secrets
Test the TLS registry config with a health check before wiring it to Mongo

When it happens

Trigger: Applying MongoClientSettings where a TLS/keystore config is present and `createSSLContext()` throws — e.g. keystore file missing/unreadable, wrong password, unsupported keystore type, or invalid truststore configuration.

Common situations: Keystore path typo or file not packaged in container; keystore password changed in secrets without updating config; using a JKS keystore with an algorithm not available in the runtime (e.g. native image missing provider); hostname verification + TLS registry misconfiguration.

Understand the failure class

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

Related errors

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/4442d2d2b1db15b4. Report an issue: GitHub.