apache/cassandra · error · ConfigurationException

MutualTlsWithPasswordFallbackAuthenticator requires client_e

Error message

MutualTlsWithPasswordFallbackAuthenticator requires client_encryption_options.require_client_auth to be optional/true

What it means

Thrown as a ConfigurationException when MutualTlsWithPasswordFallbackAuthenticator is configured but client_encryption_options.require_client_auth is NOT_REQUIRED. This authenticator needs client certificates to be at least optional so it can attempt mTLS authentication before falling back to password.

Source

Thrown at src/java/org/apache/cassandra/auth/MutualTlsWithPasswordFallbackAuthenticator.java:87

    public SaslNegotiator newSaslNegotiator(InetAddress clientAddress, Certificate[] certificates)
    {
        if (certificates == null || certificates.length == 0)
        {
            // If no certificates present, fallback to PasswordAuthentication
            return newSaslNegotiator(clientAddress);
        }
        // Otherwise attempt to authenticate using the client-provided certificate.
        return mutualTlsAuthenticator.newSaslNegotiator(clientAddress, certificates);
    }

    @Override
    public void validateConfiguration() throws ConfigurationException
    {
        Config config = DatabaseDescriptor.getRawConfig();
        if (config.client_encryption_options.getClientAuth() == EncryptionOptions.ClientEncryptionOptions.ClientAuth.NOT_REQUIRED)
        {
            String msg = "MutualTlsWithPasswordFallbackAuthenticator requires client_encryption_options.require_client_auth to be optional/true";
            throw new ConfigurationException(msg);
        }
    }
}

View on GitHub (pinned to 88fd0f6a0e)

Solutions

Set client_encryption_options.require_client_auth: true (or optional) in cassandra.yaml
Ensure client_encryption_options.enabled is true so the setting takes effect
Restart the node

Example fix

// before
client_encryption_options:
  enabled: true
  require_client_auth: false
// after
client_encryption_options:
  enabled: true
  require_client_auth: optional

Defensive patterns

Strategy: validation

Validate before calling

# require_client_auth must be optional/true when using the fallback authenticator
grep 'require_client_auth' cassandra.yaml

Try / catch

try { authenticator.validateConfiguration(); }
catch (ConfigurationException e) { LOG.error("client_encryption_options misconfigured: " + e.getMessage()); throw e; }

Prevention

Enable client encryption and set require_client_auth before choosing this authenticator
Keep client_encryption_options and authenticator choice in one config-management template

When it happens

Trigger: Selecting MutualTlsWithPasswordFallbackAuthenticator as the authenticator while client_encryption_options has require_client_auth: false (ClientAuth NOT_REQUIRED).

Common situations: Enabling the fallback authenticator on the native-transport (client) side without turning on client certificate enforcement; upgrading configs where require_client_auth defaulted to false.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

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