apache/rocketmq · error · MQClientException

Find Filter Server Failed, Broker Addr: {brokerAddr} topic:

Error message

Find Filter Server Failed, Broker Addr: {brokerAddr} topic: {topic}

What it means

Thrown by PullAPIWrapper.findFilterServerAddr when the client's cached topic route data contains no filter-server list for the given broker address. Class-filter (server-side Java filter) consumption requires a separately deployed Filtersrv; its addresses are carried in TopicRouteData.filterServerTable. If that table has no entry for the broker, the client cannot upload the filter class, so class filtering fails.

Source

Thrown at client/src/main/java/org/apache/rocketmq/client/impl/consumer/PullAPIWrapper.java:311

        return MixAll.MASTER_ID;
    }

    private String computePullFromWhichFilterServer(final String topic, final String brokerAddr)
        throws MQClientException {
        ConcurrentMap<String, TopicRouteData> topicRouteTable = this.mQClientFactory.getTopicRouteTable();
        if (topicRouteTable != null) {
            TopicRouteData topicRouteData = topicRouteTable.get(topic);
            if (topicRouteData != null && topicRouteData.getFilterServerTable() != null) {
                List<String> list = topicRouteData.getFilterServerTable().get(brokerAddr);

                if (list != null && !list.isEmpty()) {
                    return list.get(randomNum() % list.size());
                }
            }
        }

        throw new MQClientException("Find Filter Server Failed, Broker Addr: " + brokerAddr + " topic: "
            + topic, null);
    }

    public boolean isConnectBrokerByUser() {
        return connectBrokerByUser;
    }

    public void setConnectBrokerByUser(boolean connectBrokerByUser) {
        this.connectBrokerByUser = connectBrokerByUser;

    }

    public int randomNum() {
        int value = random.nextInt();
        if (value < 0) {
            value = Math.abs(value);
            if (value < 0)
                value = 0;

View on GitHub (pinned to 293f588571)

Solutions

1. Deploy or restart the Filtersrv and confirm the broker registers it (broker config filterNum/filterServerNum, check broker log 'filter server' registration), then refresh client routes
2. Prefer SQL92 filtering (MessageSelector.bySql) which runs in-broker since 4.1.0 and needs no Filtersrv
3. If staying with class filters, verify TopicRouteData.filterServerTable via mqadmin topicRoute and ensure the key matches the broker address the client is using

Example fix

// before
consumer.subscribe(topic, "com.acme.MyFilter", src); // no Filtersrv deployed -> find fails
// after: switch to in-broker SQL92, no Filtersrv needed
consumer.subscribe(topic, MessageSelector.bySql("orderAmount > 1000"));

DefaultMQAdminExt admin = new DefaultMQAdminExt(); admin.start();
TopicRouteData route = admin.examineTopicRouteInfo(topic);
boolean hasFs = route.getFilterServerTable() != null && !route.getFilterServerTable().isEmpty();
if (!hasFs) throw new IllegalStateException("no Filtersrv registered; class filters unavailable");

try { consumer.subscribe(topic, cls, src); } catch (MQClientException e) { if (String.valueOf(e.getCause()).contains("Filter Server") || /* pull-time */ true) { log.error("Filtersrv missing, falling back to SQL92"); consumer.subscribe(topic, MessageSelector.bySql(sqlExpr)); } }

When it happens

Trigger: A consumer in class-filter mode (subscribe(topic, className, source)) attempts to register the filter and findFilterServerAddr finds filterServerTable null, missing the brokerAddr key, or an empty list — for example when the deployment runs no Filtersrv instances or the broker failed to register its filter servers with the NameServer.

Common situations: Enabling class filtering without deploying the Filtersrv component (default installs omit it); Filtersrv crashed or not configured on the broker (filterServerNum in broker config); route cache on the client predates filter server registration; using class filters against broker versions/distros that dropped Filtersrv support in favor of SQL92.

Related errors

• The broker[{brokerName}] not exist
• datetime is null.
• authentication header is incorrect.
• authentication keyValues length is incorrect, actual length=
• authentication credential length is incorrect, actual length

AI-assisted analysis of apache/rocketmq@293f588571 (2026-08-14). Data as JSON: /api/errors/88389efcedf1d734. Report an issue: GitHub.