Fix – Unexpected Kafka Request of Type METADATA During SASL Handshake

Kafka clients and servers communicate using a protocol that includes various request types, one of which is METADATA. This request type is crucial as it allows a client, such as a producer or consumer, to retrieve information about the current state of the Kafka cluster, including topics, partitions, and the broker nodes. When setting up Kafka to use the Simple Authentication and Security Layer (SASL) for client authentication, a protocol handshake is required to establish a secure connection between the client and the server.

However, when configuring security protocols, users may sometimes encounter an “Unexpected Kafka request of type METADATA during SASL handshake” error. This issue generally signals that there is an unexpected sequence of events taking place during the SASL authentication process. SASL handshake is a critical step where the client and server exchange security mechanisms, agree upon an authentication method and verify each other’s authenticity. If a METADATA request is sent before the authentication process is completed, this error will arise, which could suggest a potentially misconfigured client or an issue within the Kafka server’s security setup.

Understanding Kafka and The SASL Handshake

Basics of Kafka

Apache Kafka is a high-throughput distributed messaging system designed to handle the transfer of data between servers and Kafka clients, which include producers and consumers. Producers are clients that publish (send) events to Kafka topics, while brokers are Kafka servers that store those events until they are consumed. Clients talk to Kafka brokers using a set protocol, typically defined by the security.protocol configuration.

Role of SASL in Kafka Security

SASL is an authentication framework that permits Kafka clients to authenticate with Kafka brokers. It can be set up using various mechanisms, including SASL_PLAINTEXT and SASL_PLAIN, which indicates that the client’s credentials will be sent over the network as plain text. This is why it’s often used with encryption to ensure security. The SASL.handshake is an initial exchange over the network whereby the client and broker agree on the authentication method. Properly configured listeners and the sasl.mechanism in the Kafka broker settings are vital to avoid unexpected errors during the SASL handshake.

When a Kafka producer initiates a connection to a broker, it expects a certain flow of communication as governed by the Kafka protocol and the security.protocol set. If this flow is disrupted or unexpected messages are sent—for instance, a METADATA request during the SASL handshake—a failed authentication error may occur. This error message implies that the agreed-upon security.protocol and the actual sequence of requests does not match up, causing the broker to terminate the connection as it may interpret this as a potential security threat.

Replicate the issue

Replicating an issue helps us to understand the issue better and to provide effective solutions. Below is a step-by-step guide that involves configuring both the Kafka broker and the client in a way that intentionally misaligns with the expected authentication process.

Step 1: Set Up Kafka Environment

Make sure you have a Cluster/Kafka Broker running

Step 2: Configure Kafka Broker for SASL Authentication

Enable SASL Authentication on the Broker: Modify the Kafka broker’s configuration to enable SASL authentication. This is done by editing the file of your Kafka broker to include SASL configurations. For instance, you can enable SASL_PLAINTEXT (for non-TLS encryption) or SASL_SSL (for TLS encryption) as the listener and specify the SASL mechanism (e.g., PLAIN, SCRAM-SHA-256).propertiesCopy


NOTE: This example uses SASL_PLAINTEXT for simplicity, but in a real-world scenario, SASL_SSL is recommended for encryption.

Specify SASL Configuration: Depending on the chosen SASL mechanism, you may need to provide additional configuration, such as a JAAS config file for user credentials.

Step 3: Misconfigure Kafka Client

Incorrect Client Configuration: Configure the Kafka client with the correct SASL settings but intentionally set it to communicate using a non-SASL security protocol at first. For example, you can configure the client to use SASL_SSL but start the client with PLAINTEXT or an incorrect SASL mechanism. In the client’s configuration,

properties.put("bootstrap.servers", "localhost:9092");
properties.put("security.protocol", "PLAINTEXT");
properties.put("sasl.mechanism", "PLAIN");

This misconfiguration intentionally mismatches the security protocol, leading to an attempt to send metadata requests without completing the SASL handshake.

By following the above steps you can able to replicate the error “Unexpected Kafka request of type METADATA during SASL handshake”

INFO [kafka-network-thread-9384928343-ListenerName(SASL_PLAINTEXT)-SASL_PLAINTEXT-4]: [SocketServer listenerType=BROKER, nodeId=9384928343] Failed authentication with /<ip address> (channelId=<ip address>:9092 (Unexpected Kafka request of type METADATA during SASL handshake.)

To resolve it, We need to make sure the security.protocol is the same in both the Kafka broker and client


Common Kafka SASL Errors

Let’s understand about the common SASL errors in Kafka

Understanding Metadata Requests

Metadata requests within Apache Kafka are integral for producers and consumers to find out which servers host the partitions they wish to interact with. When a client sees an Unexpected Kafka request of type METADATA during SASL handshake, it typically indicates that the client initiated a metadata query before completing the necessary SASL authentication, a step incompatible with the Kafka protocol. This error is often accompanied by detailed logs that can aid in pinpointing the problem during the debug phase.

Identification of SASL Errors

To identify SASL errors, administrators turn to the logs, where failed authentication attempts are recorded. The error logs include vital clues such as timestamps and node identifiers, which can guide an admin toward understanding whether the issue lies in the configuration or sequencing of authentication requests. Precise error messages can also distinguish between issues like network failures and incorrect credentials.

IllegalSaslStateException and Its Implications

When a Kafka client or server throws an IllegalSaslStateException, it signifies a protocol breach in the SASL mechanism. This exception flags irregularities in the state of SASL negotiations and requires immediate attention to rectify the root cause, often found through a meticulous examination of debug logs. Not addressing this may lead to halted data streams and subsequent application failures, emphasizing the importance of having a robust error-handling strategy.

By dissecting the Kafka SASL errors, especially unexpected metadata requests during the handshake process, developers and system administrators can ensure the security and fluidity of Kafka clusters.

Troubleshooting and Resolving Issues

When unexpected Kafka requests of type METADATA occur during SASL handshakes, it indicates that there are issues that need to be addressed meticulously. System administrators and developers must adopt a structured approach to identify the root cause and resolve it efficiently.

Analyzing Broker and Client Logs

One must begin by examining the broker logs for error messages that point to authentication failures or SaslHandshakeRequests. Looking at these logs, one can often tell if the Kafka broker received an unexpected metadata request while trying to establish a secured connection with the client. It is important to increase the logging level to DEBUG for a more comprehensive analysis, as this may reveal hidden IOExceptions or issues with the networkclient.

Configuration Checks

Review the properties files of both the broker and the client for any configuration errors. Key properties like security.protocol, sasl.mechanism, and sasl.jaas.config must be checked for correctness on both sides. It is also essential to ensure that the versions of Kafka used by the producer and the broker are compatible.

Network and Broker Communication Analysis

Lastly, one should analyze the network communication between the Kafka client and the broker. Any networkclient client-related errors indicated in the logs could suggest network partitioning or misconfigurations in the environment. It is necessary to verify the connectivity using tools like telnet or ping to ensure that the Kafka broker is reachable and there is no IOException hindering the communication process.

Example: telnet <hostname> <port>

By carrying out these steps, one can typically identify and rectify the unexpected error encountered during the Kafka SASL handshake phase.


In addressing the Unexpected Kafka request of type METADATA during the SASL handshake issue, it is clear that the problem typically stems from a misconfiguration in the SASL authentication process. A user may encounter this error when attempting to send messages from their producer to the Kafka server.

Resolving this error requires a methodical approach, necessitating an understanding of Kafka’s authentication mechanisms and the careful implementation of security protocols. It is a solvable issue when one systematically checks configurations and consults available resources.

Happy Learning !!

Jerry Richard
Follow me

Was this post helpful?

Thanks for your feedback!

Leave a Comment