apache/kafka · error · SchemaException

Buffer underflow while parsing response for request with…

Error message

Buffer underflow while parsing response for request with header {}

What it means

Thrown by NetworkClient.parseResponse() when AbstractResponse.parseResponse encounters a BufferUnderflowException — the response ByteBuffer does not contain enough bytes to satisfy the expected schema for the given request header. Wrapped in a SchemaException to indicate wire-protocol-level corruption.

Solutions

Verify client and broker Kafka versions are compatible (check supported API version ranges).
Check for network-level issues: MTU mismatches, proxies, or load balancers truncating large responses.
Ensure the endpoint is actually a Kafka broker and not a misrouted service.
Enable DEBUG/TRACE logging on org.apache.kafka.clients to inspect the request header and response size.

Defensive patterns

Strategy: try-catch

Try / catch

try {
    NetworkClient.parseResponse(buf, header);
} catch (SchemaException e) {
    // protocol corruption: log header, close connection, do not retry same bytes
}

Prevention

Keep client and broker versions aligned to avoid schema mismatches.
Monitor for BufferUnderflow/SchemaException rates as a network-health signal.
Ensure no proxy truncates Kafka traffic (check MTU/load-balancer config).

When it happens

Trigger: A response arrives whose byte length is shorter than the schema demands for the API key/version in the request header. Caused by truncated network reads, mismatched protocol versions between client and broker, or a malformed/corrupt response payload.

Common situations: Client/broker version skew where the broker sends a response in an older/newer format than expected, network-layer corruption or MTU truncation, a buggy or non-Kafka server responding on the Kafka port, or a partially-written response due to connection teardown.

Related errors

AI-assisted analysis of apache/kafka@996fb4585a (2026-08-11). Data as JSON: /api/errors/89e247e7511c17f5. Report an issue: GitHub.

Appendix: source

Thrown at clients/src/main/java/org/apache/kafka/clients/NetworkClient.java:921

     * <p>
     * If bootstrap is disabled or already complete, throw IllegalStateException.
     * If bootstrap is enabled but not yet complete, return an empty {@link LeastLoadedNode}
     * so that the caller can continue polling while DNS resolution finishes.
     */
    private LeastLoadedNode handleEmptyNodeList() {
        if (bootstrapConfiguration == BootstrapConfiguration.DISABLED || metadataUpdater.isBootstrapped()) {
            throw new IllegalStateException("There are no nodes in the Kafka cluster");
        }

        log.debug("No nodes available yet, still in bootstrap phase");
        return new LeastLoadedNode(null, false);
    }

    public static AbstractResponse parseResponse(ByteBuffer responseBuffer, RequestHeader requestHeader) {
        try {
            return AbstractResponse.parseResponse(responseBuffer, requestHeader);
        } catch (BufferUnderflowException e) {
            throw new SchemaException("Buffer underflow while parsing response for request with header " + requestHeader, e);
        } catch (CorrelationIdMismatchException e) {
            if (SaslClientAuthenticator.isReserved(requestHeader.correlationId())
                && !SaslClientAuthenticator.isReserved(e.responseCorrelationId()))
                throw new SchemaException("The response is unrelated to Sasl request since its correlation id is "
                    + e.responseCorrelationId() + " and the reserved range for Sasl request is [ "
                    + SaslClientAuthenticator.MIN_RESERVED_CORRELATION_ID + ","
                    + SaslClientAuthenticator.MAX_RESERVED_CORRELATION_ID + "]");
            else {
                throw e;
            }
        }
    }

    /**
     * Post process disconnection of a node
     *
     * @param responses The list of responses to update
     * @param nodeId Id of the node to be disconnected

View on GitHub (pinned to 996fb4585a)