apache/cassandra · critical · ConfigurationException

(dynamic failureMessage from provider installation/health ch

Error message

(dynamic failureMessage from provider installation/health check)

What it means

When installing a custom crypto provider fails (e.g. the provider class can't be found/initialized, or a health check such as fetching a KeyGenerator fails), AbstractCryptoProvider wraps the root cause's message in a ConfigurationException if failOnMissingProvider is true; otherwise it only logs a warning. It signals the configured crypto provider is not usable.

Source

Thrown at src/java/org/apache/cassandra/security/AbstractCryptoProvider.java:175

                                    getProviderClassAsString(), ex.getMessage());
            t = ex;
        }

        if (failureMessage != null)
        {
            // To be sure there is not any leftover, proactively remove this provider in case of any failure.
            // This method returns silently if the provider is not installed or if name is null.
            try
            {
                uninstall();
            }
            catch (Throwable throwable)
            {
                logger.warn("Uninstallation of {} failed", getProviderName(), throwable);
            }

            if (failOnMissingProvider)
                throw new ConfigurationException(failureMessage, t);
            else
                logger.warn(failureMessage);
        }
    }

    /**
     * Uninstalls this crypto provider of name {@link #getProviderName()}
     *
     * @see Security#removeProvider(String)
     */
    public void uninstall()
    {
        Security.removeProvider(getProviderName());
    }

    private int getProviderPosition(String providerName)
    {
        Provider[] providers = Security.getProviders();

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Read the wrapped failureMessage — it carries the underlying cause of the installation failure
Verify crypto_provider.class_name is correct and the provider JAR is on the classpath
Test the provider standalone (Security.addProvider + KeyGenerator.getInstance) with the same JDK
Set fail_on_missing_provider=false only if the default JDK provider fallback is acceptable
Fix the underlying cause (missing JCE policy, HSM connectivity, key config) and restart

Example fix

// cassandra.yaml before
crypto_provider:
  - class_name: com.example.MissingProvider
    parameters:
      - fail_on_missing_provider: true
// after: use a provider that exists on the classpath
crypto_provider:
  - class_name: com.amazon.corretto.crypto.provider.AmazonCorrettoCryptoProvider
    parameters:
      - fail_on_missing_provider: false

Defensive patterns

Strategy: try-catch

Validate before calling

try { KeyGenerator kg = KeyGenerator.getInstance(algorithm, providerName); } catch (Exception e) { /* provider unavailable — fix config before install */ }

Type guard

boolean providerUsable(Provider p) { try { KeyGenerator.getInstance("AES", p); return true; } catch (Exception e) { return false; } }

Try / catch

try { cryptoProvider.install(); } catch (ConfigurationException e) { logger.error("Crypto provider failed to install: {}", e.getMessage()); throw new StartupFailure(e); }

Prevention

Verify provider class name and JAR presence on the classpath at startup
Test provider installation in CI with the same JDK/JCE configuration
Keep fail_on_missing_provider=true in production to fail fast instead of silent fallback
Monitor logs for the warning path when fail_on_missing_provider=false

When it happens

Trigger: Calling AbstractCryptoProvider.install() (directly or via testCryptoProviderInstallation) when provider creation/registration throws a Throwable and the 'fail_on_missing_provider' config option is enabled — e.g. bad crypto_provider configuration in cassandra.yaml or a JCE provider missing from the classpath.

Common situations: Configuring crypto_provider in cassandra.yaml with a misspelled class name; missing provider JARs on the classpath (FIPS/HSM providers); JDK upgrades removing a provider; expired/broken key material causing health-check failures.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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