apache/shardingsphere · error · HandshakeException

1043

1043

Error message

Bad handshake

What it means

Error "Bad handshake" thrown in apache/shardingsphere.

Source

Thrown at proxy/frontend/dialect/mysql/src/main/java/org/apache/shardingsphere/proxy/frontend/mysql/authentication/MySQLAuthenticationEngine.java:119

            authenticateMismatchedMethod((MySQLPacketPayload) payload);
        }
        Grantee grantee = new Grantee(currentAuthResult.getUsername(), getHostAddress(context));
        ShardingSpherePreconditions.checkState(login(rule, grantee, authResponse), () -> new AccessDeniedException(currentAuthResult.getUsername(), grantee.getHostname(), 0 != authResponse.length));
        ShardingSpherePreconditions.checkState(authorizeDatabase(rule, grantee, currentAuthResult.getDatabase()),
                () -> new DatabaseAccessDeniedException(currentAuthResult.getUsername(), grantee.getHostname(), currentAuthResult.getDatabase()));
        writeOKPacket(context);
        return AuthenticationResultBuilder.finished(grantee.getUsername(), grantee.getHostname(), currentAuthResult.getDatabase(), currentAuthResult.getConnectionAttributes());
    }
    
    private AuthenticationResult authenticatePhaseFastPath(final ChannelHandlerContext context, final PacketPayload payload, final AuthorityRule rule) {
        MySQLHandshakeResponse41Packet handshakeResponsePacket;
        try {
            handshakeResponsePacket = new MySQLHandshakeResponse41Packet((MySQLPacketPayload) payload);
        } catch (final IndexOutOfBoundsException ex) {
            if (log.isWarnEnabled()) {
                log.warn("Received bad handshake from client {}: \n{}", context.channel(), ByteBufUtil.prettyHexDump(payload.getByteBuf().resetReaderIndex()));
            }
            throw new HandshakeException();
        }
        authResponse = handshakeResponsePacket.getAuthResponse();
        setMultiStatementsOption(context, handshakeResponsePacket);
        setCharacterSet(context, handshakeResponsePacket);
        setConnectionAttributes(context, handshakeResponsePacket);
        String database = handshakeResponsePacket.getDatabase();
        ShardingSpherePreconditions.checkState(Strings.isNullOrEmpty(database) || ProxyContext.getInstance().getContextManager().getMetaDataContexts().getMetaData().containsDatabase(database),
                () -> new UnknownDatabaseException(database));
        String username = handshakeResponsePacket.getUsername();
        String hostname = getHostAddress(context);
        ShardingSphereUser user = rule.findUser(new Grantee(username, hostname)).orElseGet(() -> new ShardingSphereUser(username, "", hostname));
        Authenticator authenticator = new AuthenticatorFactory<>(MySQLAuthenticatorType.class, rule).newInstance(user);
        Map<String, String> connectionAttributes = handshakeResponsePacket.getConnectionAttributes();
        if (0 == authResponse.length || isClientPluginAuthenticate(handshakeResponsePacket) && !authenticator.getAuthenticationMethodName().equals(handshakeResponsePacket.getAuthPluginName())) {
            connectionPhase = MySQLConnectionPhase.AUTHENTICATION_METHOD_MISMATCH;
            context.writeAndFlush(new MySQLAuthSwitchRequestPacket(authenticator.getAuthenticationMethodName(), authPluginData));
            return AuthenticationResultBuilder.continued(username, hostname, database, connectionAttributes);
        }

View on GitHub (pinned to e952770a21)

Solutions

1. Verify username and password used by the client.
2. Ensure the client and server agree on the authentication plugin and protocol version.
3. Check that the connection was not interrupted or corrupted during the handshake.

When it happens

Trigger: MySQL handshake authentication fails in MySQLAuthenticationEngine, e.g. wrong credentials or protocol mismatch.

Common situations: Bad password, unsupported client auth plugin, or TLS/packet corruption during the initial handshake.

Understand the failure class

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

AI-assisted analysis of apache/shardingsphere@e952770a21 (2026-08-14). Data as JSON: /api/errors/b6fac46e95056faa. Report an issue: GitHub.