apache/cassandra · critical · IllegalStateException

Unrecognized TLS encryption policy:

Error message

Unrecognized TLS encryption policy: 

What it means

IllegalStateException thrown during pipeline configuration when the configured client/server encryption option string does not match any recognized TLS encryption policy value. Cassandra only accepts a fixed set of encryption settings; anything else means the operator misspelled or supplied an unsupported value in cassandra.yaml, so startup/configuration is aborted. Unlike ProtocolException, this signals a server configuration problem, not a client protocol issue.

Source

Thrown at src/java/org/apache/cassandra/transport/PipelineConfigurator.java:248

                                // Connection use no TLS/SSL encryption, just remove the detection handler and continue without
                                // SslHandler in the pipeline.
                                channelHandlerContext.pipeline().remove(SSL_HANDLER);
                            }
                        }
                    });
                };
            case ENCRYPTED:
                logger.debug("Enabling encrypted CQL connections between client and server");
                return channel -> {
                    SslContext sslContext = SSLFactory.getOrCreateSslContext(encryptionOptions,
                                                                             encryptionOptions.getClientAuth(),
                                                                             ISslContextFactory.SocketType.SERVER,
                                                                             SSL_FACTORY_CONTEXT_DESCRIPTION);
                    InetSocketAddress peer = encryptionOptions.require_endpoint_verification ? (InetSocketAddress) channel.remoteAddress() : null;
                    channel.pipeline().addFirst(SSL_HANDLER, newSslHandler(channel, sslContext, peer));
                };
            default:
                throw new IllegalStateException("Unrecognized TLS encryption policy: " + this.tlsEncryptionPolicy);
        }
    }

    public void configureInitialPipeline(Channel channel, Connection.Factory connectionFactory)
    {
        ChannelPipeline pipeline = channel.pipeline();

        // Add the ConnectionLimitHandler to the pipeline if configured to do so.
        if (DatabaseDescriptor.getNativeTransportMaxConcurrentConnections() > 0
            || DatabaseDescriptor.getNativeTransportMaxConcurrentConnectionsPerIp() > 0)
        {
            // Add as first to the pipeline so the limit is enforced as first action.
            pipeline.addFirst(CONNECTION_LIMIT_HANDLER, connectionLimitHandler);
        }

        long idleTimeout = DatabaseDescriptor.nativeTransportIdleTimeout();
        if (idleTimeout > 0)
        {

View on GitHub (pinned to 88fd0f6a0e)

Solutions

1. Correct the encryption option value in cassandra.yaml to a supported setting (e.g. valid ssl_storage_port/client encryption options such as enabled: true/false).
2. Compare against the documented encryption_options for your Cassandra version; remove deprecated keys.
3. Validate cassandra.yaml with config-validation enabled before restart.
4. Check change history of the config file for recently edited encryption blocks.

Example fix

# before
cassandra.yaml:
  client_encryption_options:
    enable: true
# after
  client_encryption_options:
    enabled: true

# validate encryption config before restart
grep -E '^\s*(enabled|require_client_auth)\s*:' cassandra.yaml  # only recognized keys/values allowed

When it happens

Trigger: encryption_options in cassandra.yaml (or the programmatic equivalent passed to PipelineConfigurator.encryptionConfig) contains a value other than the recognized options (e.g. true/false/unrecognized string) — commonly a typo such as 'enable' or an option name from an older version.

Common situations: Upgrading Cassandra and carrying over deprecated encryption option names, typos in cassandra.yaml, copy-pasted configs from other databases, or templating systems injecting wrong values.

Understand the failure class

• SSL/TLS and certificate errors — how TLS handshakes and certificate validation fail.

Related errors

• legacy_ssl_storage_port_enabled is true (enabled) with inter
• Setting server_encryption_options.enabled has no effect, use
• Load CIDR groups cache operation not supported by %s
• Unsupported parameter '%s' for %s, supported parameters are
• Configured node identity is not matching identity extractedf

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