apache/cassandra · error · ConfigurationException

Local endpoint port doesn't match YAML configured port or…

Error message

Local endpoint port %d doesn't match YAML configured port %d or legacy SSL port %d

What it means

InboundConnectionSettings.withDefaults() validates that the port of the configured bind address matches either the YAML storage_port or the legacy ssl_storage_port. If the bind address carries a port that corresponds to neither, a ConfigurationException naming both expected ports is thrown.

Solutions

Use DatabaseDescriptor.getStoragePort() (or getSSLStoragePort()) when constructing the bind InetSocketAddress
Fix cassandra.yaml so storage_port matches the port used in the bind address
In tests, derive the port from DatabaseDescriptor values instead of hardcoding
Rebuild settings objects after changing DatabaseDescriptor configuration

Example fix

// before
InboundConnectionSettings s = new InboundConnectionSettings().withBindAddress(new InetSocketAddress(host, 9999));
// after
InboundConnectionSettings s = new InboundConnectionSettings().withBindAddress(new InetSocketAddress(host, DatabaseDescriptor.getStoragePort()));

Defensive patterns

Strategy: validation

Validate before calling

// before building InboundConnectionSettings
int port = bindAddress.getPort();
if (port != DatabaseDescriptor.getStoragePort() && port != DatabaseDescriptor.getSSLStoragePort())
    throw new IllegalArgumentException("port " + port + " must equal storage_port or ssl_storage_port");

Prevention

Always derive ports from DatabaseDescriptor rather than hardcoding
Keep cassandra.yaml storage_port consistent with any programmatically built settings
In tests, use the same port source as production code paths
Rebuild settings objects after changing DatabaseDescriptor configuration

When it happens

Trigger: Constructing an InboundConnectionSettings with a bind address whose port differs from DatabaseDescriptor.getStoragePort() and getSSLStoragePort() — typically in tests or embedded setups that build messaging settings by hand.

Common situations: Test code binding an arbitrary ephemeral port; changing storage_port in cassandra.yaml after settings objects were built; pre-4.0 messaging interop paths that rewrite ports.

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.

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

Related errors

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

Appendix: source

Thrown at src/java/org/apache/cassandra/net/InboundConnectionSettings.java:163

    public InboundConnectionSettings withLegacySslStoragePortDefaults()
    {
        ServerEncryptionOptions encryption = this.encryption;
        if (encryption == null)
            encryption = DatabaseDescriptor.getInternodeMessagingEncyptionOptions();
        encryption = new ServerEncryptionOptions.Builder(encryption).withInternodeEncryption(ServerEncryptionOptions.InternodeEncryption.all).withOptional(false).build();

        return this.withBindAddress(bindAddress.withPort(DatabaseDescriptor.getSSLStoragePort()))
                   .withEncryption(encryption)
                   .withDefaults();
    }

    // note that connectTo is updated even if specified, in the case of pre40 messaging and using encryption (to update port)
    public InboundConnectionSettings withDefaults()
    {
        // this is for the socket that can be plain, only ssl, or optional plain/ssl
        if (bindAddress.getPort() != DatabaseDescriptor.getStoragePort() && bindAddress.getPort() != DatabaseDescriptor.getSSLStoragePort())
            throw new ConfigurationException(format("Local endpoint port %d doesn't match YAML configured port %d or legacy SSL port %d",
                                                    bindAddress.getPort(), DatabaseDescriptor.getStoragePort(), DatabaseDescriptor.getSSLStoragePort()));

        IInternodeAuthenticator authenticator = this.authenticator;
        ServerEncryptionOptions encryption = this.encryption;
        Integer socketReceiveBufferSizeInBytes = this.socketReceiveBufferSizeInBytes;
        Integer applicationReceiveQueueCapacityInBytes = this.applicationReceiveQueueCapacityInBytes;
        AcceptVersions acceptMessaging = this.acceptMessaging;
        AcceptVersions acceptStreaming = this.acceptStreaming;
        SocketFactory socketFactory = this.socketFactory;
        Function<InetAddressAndPort, InboundMessageHandlers> handlersFactory = this.handlers;

        if (authenticator == null)
            authenticator = DatabaseDescriptor.getInternodeAuthenticator();

        if (encryption == null)
            encryption = DatabaseDescriptor.getInternodeMessagingEncyptionOptions();

        if (socketReceiveBufferSizeInBytes == null)

View on GitHub (pinned to 88fd0f6a0e)