apache/kafka · error · MismatchedEndpointTypeException

Expected response from CONTROLLER endpoint, but got…

Error message

Expected response from CONTROLLER endpoint, but got response from endpoint type {endpointType}

What it means

A MismatchedEndpointTypeException thrown while parsing a DescribeClusterResponse when the client expected a response from a CONTROLLER endpoint (because it is using bootstrap.controllers) but the response's endpointType field indicates a different endpoint type. It signals a topology/routing mismatch between what the client asked for and what the cluster returned.

Solutions

Verify bootstrap.controllers points at controller listener ports (typically 9093), not broker ports.
Check advertised.listeners/controller.quorum.voters on the cluster side to ensure controller endpoints advertise as controllers.
Retry after the cluster stabilizes if the error appeared during a controller failover.

Example fix

// before
props.put("bootstrap.controllers", "host1:9092,host2:9092"); // broker ports

// after
props.put("bootstrap.controllers", "host1:9093,host2:9093"); // controller ports

Defensive patterns

Strategy: validation

Validate before calling

// verify controller ports before relying on bootstrap.controllers
// (no client-side guard beyond correct config; see preventionTips)

Try / catch

try {
    admin.describeCluster(opts).nodes().get();
} catch (ExecutionException e) {
    if (e.getCause() instanceof MismatchedEndpointTypeException) {
        // reconfigure bootstrap.controllers to controller listener ports, retry
    }
}

Prevention

Point bootstrap.controllers only at controller listener ports (e.g. 9093).
Verify advertised.listeners/controller.quorum.voters match the controller endpoints.
Retry after a controller failover if the error is transient.

When it happens

Trigger: Admin client configured with bootstrap.controllers sending DescribeCluster with endpointType=CONTROLLER, but the responding node reports a non-CONTROLLER endpointType. Happens when a controller-listed address actually routes to a broker, or when the cluster is in a mixed/transitioning state.

Common situations: Misconfigured advertised listeners where a controller listener is actually a broker listener; pointing bootstrap.controllers at broker ports by mistake; cluster in the middle of a KRaft controller switch; version skew where endpointType semantics differ.

Related errors

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

Appendix: source

Thrown at clients/src/main/java/org/apache/kafka/clients/admin/KafkaAdminClient.java:1811

                    metadataManager.updateFailed(e);
                    return false;
                }

                @Override
                public void handleFailure(Throwable e) {
                    metadataManager.updateFailed(e);
                }
            };
        }
    }

    static Cluster parseDescribeClusterResponse(DescribeClusterResponseData response) {
        ApiError apiError = new ApiError(response.errorCode(), response.errorMessage());
        if (apiError.isFailure()) {
            throw apiError.exception();
        }
        if (response.endpointType() != EndpointType.CONTROLLER.id()) {
            throw new MismatchedEndpointTypeException("Expected response from CONTROLLER " +
                "endpoint, but got response from endpoint type " + (int) response.endpointType());
        }
        List<Node> nodes = new ArrayList<>();
        Node controllerNode = null;
        for (DescribeClusterResponseData.DescribeClusterBroker node : response.brokers()) {
            Node newNode = new Node(node.brokerId(), node.host(), node.port(), node.rack());
            nodes.add(newNode);
            if (node.brokerId() == response.controllerId()) {
                controllerNode = newNode;
            }
        }
        return new Cluster(response.clusterId(),
            nodes,
            Collections.emptyList(),
            Collections.emptySet(),
            Collections.emptySet(),
            controllerNode);
    }

View on GitHub (pinned to 996fb4585a)