apache/cassandra · error · ConfigurationException

MutualTlsInternodeAuthenticator requires server_encryption_o

Error message

MutualTlsInternodeAuthenticator requires server_encryption_options.internode_encryption to be enabled & server_encryption_options.require_client_auth to be true

What it means

Thrown during validateConfiguration() as a ConfigurationException when the authenticator is selected but the server-side encryption settings do not actually enforce mutual TLS. mTLS internode authentication is meaningless unless internode encryption is enabled and client (peer) certificate auth is required.

Source

Thrown at src/java/org/apache/cassandra/auth/MutualTlsInternodeAuthenticator.java:176

    @Override
    public boolean authenticate(InetAddress remoteAddress, int remotePort, Certificate[] certificates, InternodeConnectionDirection connectionType)
    {
        return authenticateInternodeWithMtls(remoteAddress, remotePort, certificates, connectionType);
    }


    @Override
    public void validateConfiguration() throws ConfigurationException
    {
        Config config = DatabaseDescriptor.getRawConfig();
        if (config.server_encryption_options.internode_encryption == EncryptionOptions.ServerEncryptionOptions.InternodeEncryption.none
            || config.server_encryption_options.getClientAuth() != REQUIRED)
        {
            String msg = "MutualTlsInternodeAuthenticator requires server_encryption_options.internode_encryption to be enabled" +
                         " & server_encryption_options.require_client_auth to be true";
            logger.error(msg);
            throw new ConfigurationException(msg);
        }
    }

    protected boolean authenticateInternodeWithMtls(InetAddress remoteAddress, int remotePort, Certificate[] certificates,
                                                    IInternodeAuthenticator.InternodeConnectionDirection connectionType)
    {
        if (connectionType == IInternodeAuthenticator.InternodeConnectionDirection.INBOUND)
        {
            String identity = certificateValidator.identity(certificates);
            if (!certificateValidator.isValidCertificate(certificates))
            {
                noSpamLogger.error("Not a valid certificate from {}:{} with identity '{}'", remoteAddress, remotePort, identity);
                return false;
            }

            if (!trustedIdentities.contains(identity))
            {
                noSpamLogger.error("Unable to authenticate user {}", identity);

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Set server_encryption_options.internode_encryption to dc, rack, or all (not none)
2. Set server_encryption_options.require_client_auth: true (ClientAuth REQUIRED)
3. Restart the node so validateConfiguration passes
4. Ensure the setting is identical on all nodes to avoid mixed-mode failure

Example fix

// before (cassandra.yaml)
server_encryption_options:
  internode_encryption: none
  require_client_auth: false
// after
server_encryption_options:
  internode_encryption: all
  require_client_auth: true

# before enabling the authenticator, check yaml
# server_encryption_options.internode_encryption != none AND require_client_auth: true
grep -A2 'internode_encryption' cassandra.yaml

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

When it happens

Trigger: Setting authenticator/class to MutualTlsInternodeAuthenticator while cassandra.yaml has server_encryption_options.internode_encryption: none, or require_client_auth is false (ClientAuth not REQUIRED).

Common situations: Enabling the mTLS authenticator without enabling internode_encryption; leaving require_client_auth commented/false; partial TLS configuration applied only to some nodes.

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

• Configured node identity is not matching identity extractedf
• No identity was extracted from the outbound keystore '%s'
• MutualTlsWithPasswordFallbackAuthenticator requires client_e
• Unable to extract Spiffe from the certificate
• legacy_ssl_storage_port_enabled is true (enabled) with inter

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