apache/kafka · error · IllegalArgumentException

Cannot request fenced brokers from controller endpoint

Error message

Cannot request fenced brokers from controller endpoint

What it means

An IllegalArgumentException thrown inside the listNodes Call when the client is using bootstrap.controllers (talking directly to controllers) but the options request fenced brokers to be included. The controller DescribeCluster path does not support includeFencedBrokers, so the combination is rejected before sending the request.

Solutions

1. If you need fenced brokers, configure the Admin with bootstrap.servers (broker mode) instead of bootstrap.controllers.
2. If you must use bootstrap.controllers, set includeFencedBrokers to false.
3. Gate the option on the configured bootstrap type: only enable fenced brokers when not usingBootstrapControllers().

Example fix

// before
props.put("bootstrap.controllers", "ctrl:9093");
DescribeClusterOptions opts = new DescribeClusterOptions().includeFencedBrokers(true);
admin.describeCluster(opts);

// after (need fenced brokers -> broker mode)
props.put("bootstrap.servers", "broker:9092");
admin.describeCluster(opts);

DescribeClusterOptions opts = new DescribeClusterOptions();
if (!usingBootstrapControllers) {
    opts = opts.includeFencedBrokers(true);
}
admin.describeCluster(opts);

When it happens

Trigger: Admin configured with bootstrap.controllers and calling describeCluster/listNodes with ListNodesOptions/DescribeClusterOptions that has includeFencedBrokers set to true (and the node supports the non-metadata path).

Common situations: Operator tooling that always sets includeFencedBrokers being pointed at the controller listener; scripts reused across broker-mode and controller-mode without toggling the option; cluster health checks that want fenced broker visibility.

Related errors

• Expected response from CONTROLLER endpoint, but got…
• Cannot specify a negative version level.
• Expected minVersionLevel >= 0, maxVersionLevel >= 0 and…
• Group ID not found
• List Offsets for partition

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

Appendix: source

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

    @Override
    public DescribeClusterResult describeCluster(DescribeClusterOptions options) {
        final KafkaFutureImpl<Collection<Node>> describeClusterFuture = new KafkaFutureImpl<>();
        final KafkaFutureImpl<Node> controllerFuture = new KafkaFutureImpl<>();
        final KafkaFutureImpl<String> clusterIdFuture = new KafkaFutureImpl<>();
        final KafkaFutureImpl<Set<AclOperation>> authorizedOperationsFuture = new KafkaFutureImpl<>();

        final long now = time.milliseconds();
        runnable.call(new Call("listNodes", calcDeadlineMs(now, options.timeoutMs()),
            new LeastLoadedBrokerOrActiveKController()) {

            private boolean useMetadataRequest = false;

            @Override
            AbstractRequest.Builder<?> createRequest(int timeoutMs) {
                if (!useMetadataRequest) {
                    if (metadataManager.usingBootstrapControllers() && options.includeFencedBrokers()) {
                        throw new IllegalArgumentException("Cannot request fenced brokers from controller endpoint");
                    }
                    return new DescribeClusterRequest.Builder(new DescribeClusterRequestData()
                        .setIncludeClusterAuthorizedOperations(options.includeAuthorizedOperations())
                        .setEndpointType(metadataManager.usingBootstrapControllers() ?
                            EndpointType.CONTROLLER.id() : EndpointType.BROKER.id())
                        .setIncludeFencedBrokers(options.includeFencedBrokers()));
                } else {
                    // Since this only requests node information, it's safe to pass true for allowAutoTopicCreation (and it
                    // simplifies communication with older brokers)
                    return new MetadataRequest.Builder(new MetadataRequestData()
                        .setTopics(Collections.emptyList())
                        .setAllowAutoTopicCreation(true)
                        .setIncludeClusterAuthorizedOperations(
                            options.includeAuthorizedOperations()));
                }
            }

            @Override

View on GitHub (pinned to 996fb4585a)