{"record":{"id":"1a3e4f438ff07b39","repo":"apache/cassandra","slug":"failed-to-properly-handshake-with-peer-closing","errorCode":null,"errorMessage":"Failed to properly handshake with peer {}. Closing the channel. Invalid legacy protocol magic.","messagePattern":"Failed to properly handshake with peer (.+?)\\. Closing the channel\\. Invalid legacy protocol magic\\.","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"src/java/org/apache/cassandra/net/InboundConnectionInitiator.java","lineNumber":396,"sourceCode":"        {\n            return ctx.pipeline().get(SslHandler.class) != null;\n        }\n\n        @Override\n        public void exceptionCaught(ChannelHandlerContext ctx, Throwable cause)\n        {\n            exceptionCaught(ctx.channel(), cause);\n        }\n\n        private void exceptionCaught(Channel channel, Throwable cause)\n        {\n            final SocketAddress remoteAddress = channel.remoteAddress();\n            boolean reportingExclusion = DatabaseDescriptor.getInternodeErrorReportingExclusions().contains(remoteAddress);\n\n            if (reportingExclusion)\n                logger.debug(\"Excluding internode exception for {}; address contained in internode_error_reporting_exclusions\", remoteAddress, cause);\n            else if (cause != null && Throwables.getRootCause(cause) instanceof Message.InvalidLegacyProtocolMagic && DatabaseDescriptor.getInvalidLegacyProtocolMagicNoSpamEnabled())\n                noSpam5m.warn(\"Failed to properly handshake with peer {}. Closing the channel. Invalid legacy protocol magic.\", ((InetSocketAddress) channel.remoteAddress()).getHostName());\n            else\n                logger.error(\"Failed to properly handshake with peer {}. Closing the channel.\", remoteAddress, cause);\n\n            try\n            {\n                failHandshake(channel);\n            }\n            catch (Throwable t)\n            {\n                if (!reportingExclusion)\n                    logger.error(\"Unexpected exception in {}.exceptionCaught\", this.getClass().getSimpleName(), t);\n            }\n        }\n\n        private void failHandshake(ChannelHandlerContext ctx)\n        {\n            failHandshake(ctx.channel());\n        }","sourceCodeStart":378,"sourceCodeEnd":414,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/net/InboundConnectionInitiator.java#L378-L414","documentation":"Logged when the Netty channel exception handler detects that a peer sent an internode handshake whose 'magic' value does not match any legacy protocol version Cassandra can speak. The connection is closed via failHandshake because the peer is either not a Cassandra node, runs a wildly incompatible major version, or is a non-Cassandra process on the internode port.","triggerScenarios":"exceptionCaught fires with a root cause of Message.InvalidLegacyProtocolMagic during the internode connection handshake; happens when a peer connects that cannot deserialize the initial handshake frame.","commonSituations":"Misconfigured clients pointed at the storage_port (e.g. a client using native transport port as internode), mixed-version clusters crossing incompatible majors, firewalls/proxies or load balancers health-checking the internode port, or a non-Cassandra service bound to the same port.","solutions":["Verify both endpoints run compatible Cassandra versions for the cluster (roll upgrades within supported versions).","Check that the peer really is a Cassandra node and that the address:storage_port is correct in cassandra.yaml.","Inspect internode_error_reporting_exclusions and health-checkers: exclude LB/probe IPs that hit the storage port.","Run nodetool gossipinfo / verify network connectivity and that no other service occupies storage_port.","If the peer cannot be made compatible, firewall it off or stop it from connecting."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// Before pointing any process at storage_port, verify it is a Cassandra peer:\n// nodetool gossipinfo | grep <peer-ip>\n// netstat -tlnp | grep 7000  (confirm only Cassandra binds the port)","typeGuard":null,"tryCatchPattern":"// Server-side: this is logged, not thrown to user code.\n// Suppress noise from known non-Cassandra probes via cassandra.yaml:\n// internode_error_reporting_exclusions: [<lb-ip>, <probe-ip>]","preventionTips":["Never point native-transport clients or health checks at storage_port.","Keep cluster versions within supported upgrade compatibility.","Exclude load-balancer/probe IPs via internode_error_reporting_exclusions.","Monitor this warning to detect rogue services on the internode port."],"tags":["network","internode","handshake","cassandra"],"backgroundTag":"protocol-handshake-failure","analyzedSha":"88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1","analyzedAt":"2026-09-10T07:29:22.284Z","contentChangedAt":"2026-09-10T07:29:22.284Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}