apache/cassandra · critical · ConfigurationException

failed to load key provider for transparent data encryption

Error message

failed to load key provider for transparent data encryption

What it means

EncryptionContext's constructor creates the shared CipherFactory from transparent data encryption options; any exception is wrapped in ConfigurationException with this message. It means TDE is enabled but the key provider could not be constructed, so encrypted reads/writes cannot proceed.

Solutions

Fix transparent_data_encryption_options: verify key_provider.class_name, key_provider keystore path/password, and cipher/key_alias values.
Check the wrapped cause for the precise failure (ClassNotFoundException, constructor exception).
Deploy the custom key provider JAR if one is configured.
If TDE is not intended, set transparent_data_encryption_options.enabled: false.

Example fix

// before
transparent_data_encryption_options:
  enabled: true
  key_provider:
    class_name: MissingKeyProvider
// after
transparent_data_encryption_options:
  enabled: true
  key_provider:
    class_name: org.apache.cassandra.security.JKSKeyProvider
    keystore: conf/.keystore
    keystore_password: cassandra

Defensive patterns

Strategy: validation

Validate before calling

if (tdeOptions.enabled) {
    Class.forName(tdeOptions.key_provider.class_name); // fail fast on missing class
}
// or start with TDE disabled and enable after a successful CipherFactory construction test

Try / catch

try {
    EncryptionContext ctx = DatabaseDescriptor.getEncryptionContext();
} catch (ConfigurationException e) {
    logger.error("TDE key provider invalid; fix transparent_data_encryption_options", e);
}

Prevention

Validate TDE config at config-load time before enabling
Keep a startup smoke test that constructs the key provider
Document required JARs for custom providers

When it happens

Trigger: Server startup or EncryptionContext creation when tdeOptions.enabled is true and new CipherFactory(tdeOptions) throws — typically because key_provider.class_name is missing/invalid or its constructor fails.

Common situations: Typo in key_provider class name, custom key provider JAR not on classpath, invalid key provider parameters (bad keystore path/password) in cassandra.yaml.

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/1b9f9ec8965d54f6. Report an issue: GitHub.

Appendix: source

Thrown at src/java/org/apache/cassandra/security/EncryptionContext.java:83

    {
        this.tdeOptions = tdeOptions;
        compressor = LZ4Compressor.create(Collections.<String, String>emptyMap());
        chunkLength = tdeOptions.chunk_length_kb * 1024;
        this.iv = iv;

        // always attempt to load the cipher factory, as we could be in the situation where the user has disabled encryption,
        // but has existing commitlogs and sstables on disk that are still encrypted (and still need to be read)
        CipherFactory factory = null;

        if (tdeOptions.enabled && init)
        {
            try
            {
                factory = new CipherFactory(tdeOptions);
            }
            catch (Exception e)
            {
                throw new ConfigurationException("failed to load key provider for transparent data encryption", e);
            }
        }

        cipherFactory = factory;
    }

    public ICompressor getCompressor()
    {
        return compressor;
    }

    public Cipher getEncryptor() throws IOException
    {
        return cipherFactory.getEncryptor(tdeOptions.cipher, tdeOptions.key_alias);
    }

    public Cipher getDecryptor() throws IOException
    {

View on GitHub (pinned to 88fd0f6a0e)