apache/cassandra · error · ConfigurationException

Failed to initialize crypto provider, class_name cannot be n

Error message

Failed to initialize crypto provider, class_name cannot be null

What it means

applyCryptoProvider() installs the pluggable crypto provider used for sensitive-data encryption. Its class_name is taken from system property cassandra.crypto_provider_class_name or the crypto_provider config; if neither is set the required class name is null and a ConfigurationException is thrown because no provider can be instantiated without one.

Source

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

            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");

        if (conf.crypto_provider.parameters == null)
            conf.crypto_provider.parameters = new HashMap<>();

        Map<String, String> cryptoProviderParameters = new HashMap<>(conf.crypto_provider.parameters);
        cryptoProviderParameters.putIfAbsent(AbstractCryptoProvider.FAIL_ON_MISSING_PROVIDER_KEY, "false");

        try
        {
            cryptoProvider = FBUtilities.newCryptoProvider(conf.crypto_provider.class_name, cryptoProviderParameters);
            cryptoProvider.install();
        }
        catch (Exception e)
        {
            if (e instanceof ConfigurationException)
                throw (ConfigurationException) e;
            else
                throw new ConfigurationException(String.format("Failed to initialize crypto provider %s", conf.crypto_provider.class_name), e);

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Set crypto_provider.class_name in cassandra.yaml (e.g. org.apache.cassandra.security.DefaultCryptoProvider or JCEProvider for your JCE vendor)
Or start the JVM with -Dcassandra.crypto_provider_class_name=<class> (system property beats yaml)
Remove any dependency on encrypted data/crypto features if a provider is genuinely not desired

Example fix

// cassandra.yaml before
crypto_provider:
  parameters: {}
// after
crypto_provider:
  class_name: org.apache.cassandra.security.DefaultCryptoProvider
  parameters: {}

Defensive patterns

Strategy: validation

Validate before calling

if (conf.crypto_provider == null || conf.crypto_provider.class_name == null
    && System.getProperty("cassandra.crypto_provider_class_name") == null) {
    throw new IllegalStateException("crypto_provider.class_name must be set (yaml or -Dcassandra.crypto_provider_class_name)");
}

Try / catch

try { DatabaseDescriptor.applyCryptoProvider(); } catch (ConfigurationException e) { /* configure provider, not retryable */ }

Prevention

Always ship a crypto_provider block when using data-at-rest encryption features
Remember system property overrides yaml — keep them consistent
Document the provider class in your cluster config runbook

When it happens

Trigger: Calling DatabaseDescriptor.applyCryptoProvider() at startup when transparent/legacy data encryption requires a crypto provider but neither cassandra.crypto_provider_class_name system property nor crypto_provider.class_name in cassandra.yaml is defined.

Common situations: Upgrading to a version that mandates an explicit crypto provider while migrating encrypted tables; copying a minimal cassandra.yaml that drops the crypto_provider block; enabling TDE without configuring the provider.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

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