What causes "Failed to initialize SSL" in apache/cassandra?

Verify keystore and truststore paths in client_encryption_options exist and are readable by the cassandra user (`ls -l`, `keytool -list`)

apache/cassandra · critical · ConfigurationException

Failed to initialize SSL

Error message

Failed to initialize SSL

What it means

applyEncryptionContext() tries to initialize the SSL context used for the native transport (and JMX-adjacent crypto) via SSLFactory. If loading keystores/truststores throws an IOException (missing or unreadable file, bad password, malformed keystore), it is rethrown as a ConfigurationException('Failed to initialize SSL') and startup aborts.

Source

Thrown at src/java/org/apache/cassandra/config/DatabaseDescriptor.java:1619

        if (TEST_JVM_DTEST_DISABLE_SSL.getBoolean())
            return;

        try
        {
            SSLFactory.validateSslContext("Internode messaging", conf.server_encryption_options, REQUIRED, true);
            SSLFactory.validateSslContext("Native transport", conf.client_encryption_options, conf.client_encryption_options.getClientAuth(), true);
            // For JMX SSL the validation is pretty much the same as the Native transport
            SSLFactory.validateSslContext("JMX transport", conf.jmx_server_options.jmx_encryption_options, conf.jmx_server_options.jmx_encryption_options.getClientAuth(), true);
            SSLFactory.initHotReloading(conf.server_encryption_options, conf.client_encryption_options, false);
            /*
            For JMX SSL, the hot reloading of the SSLContext is out of scope for CASSANDRA-18508.
            Since JMXServerUtil that initializes the JMX Server is used statically, it may require significant
            effort to change that behavior unlike SSLFactory used for Native transport/Internode messaging.
             */
        }
        catch (IOException e)
        {
            throw new ConfigurationException("Failed to initialize SSL", e);
        }
    }

    public static void applyCryptoProvider()
    {
        if (TEST_SKIP_CRYPTO_PROVIDER_INSTALLATION.getBoolean())
            return;

        if (conf.crypto_provider == null)
            conf.crypto_provider = new ParameterizedClass(JREProvider.class.getName(), null);

        // properties beat configuration
        String classNameFromSystemProperties = CassandraRelevantProperties.CRYPTO_PROVIDER_CLASS_NAME.getString();
        if (classNameFromSystemProperties != null)
            conf.crypto_provider.class_name = classNameFromSystemProperties;

        if (conf.crypto_provider.class_name == null)
            throw new ConfigurationException("Failed to initialize crypto provider, class_name cannot be null");

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Verify keystore and truststore paths in client_encryption_options exist and are readable by the cassandra user (`ls -l`, `keytool -list`)
Correct keystore_password/truststore_password in cassandra.yaml
Deploy the missing certificates to every node and restart
If TLS is not intended yet, set enabled: false in client_encryption_options

Example fix

// cassandra.yaml before
client_encryption_options:
  enabled: true
  keystore: /etc/cassandra/conf/keystore.jks
  keystore_password: wrongpass
// after
client_encryption_options:
  enabled: true
  keystore: /etc/cassandra/ssl/server.keystore
  keystore_password: correctPassword

Defensive patterns

Strategy: validation

Validate before calling

if (conf.client_encryption_options.enabled) {
    for (String ks : new String[]{conf.client_encryption_options.keystore, conf.client_encryption_options.truststore}) {
        java.io.File f = new java.io.File(ks);
        if (!f.canRead()) throw new IllegalStateException("Unreadable keystore: " + ks);
    }
}

Try / catch

try { DatabaseDescriptor.daemonInitialization(); } catch (ConfigurationException e) { logger.error("SSL init failed: {}", e.getMessage(), e); }

Prevention

Deploy keystores/truststores with correct ownership before enabling encryption
Test keystore/password with keytool -list on every node
Keep cert paths consistent via config management; avoid hand-edited local paths

When it happens

Trigger: Calling DatabaseDescriptor.applyEncryptionContext() during startup with client_encryption_options (or related SSL options) enabled and a keystore/truststore path that does not exist, is unreadable, or has an incorrect password.

Common situations: TLS enabled in cassandra.yaml but keystore file not deployed to the node; wrong keystore_password; file permissions after a packaging/config-management change; renamed or moved certs during a version upgrade.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

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

Related errors

AI-assisted analysis of apache/cassandra@88fd0f6a0e (2026-09-10). Data as JSON: /api/errors/ea46a0cf54d0a09f. Report an issue: GitHub.