apache/rocketmq · error · IllegalArgumentException

topic is null

Error message

topic is null

What it means

DefaultMQPullConsumerImpl.fetchMessageQueuesInBalance(String topic) throws IllegalArgumentException("topic is null") when topic is null. The method scans the rebalance processQueueTable for queues of that topic, so a null topic cannot match anything and is rejected after the isRunning() check.

Source

Thrown at client/src/main/java/org/apache/rocketmq/client/impl/consumer/DefaultMQPullConsumerImpl.java:123

    private void isRunning() throws MQClientException {
        if (this.serviceState != ServiceState.RUNNING) {
            throw new MQClientException("The consumer is not in running status, "
                + this.serviceState
                + FAQUrl.suggestTodo(FAQUrl.CLIENT_SERVICE_NOT_OK),
                null);
        }
    }

    public long fetchConsumeOffset(MessageQueue mq, boolean fromStore) throws MQClientException {
        this.isRunning();
        return this.offsetStore.readOffset(mq, fromStore ? ReadOffsetType.READ_FROM_STORE : ReadOffsetType.MEMORY_FIRST_THEN_STORE);
    }

    public Set<MessageQueue> fetchMessageQueuesInBalance(String topic) throws MQClientException {
        this.isRunning();
        if (null == topic) {
            throw new IllegalArgumentException("topic is null");
        }

        ConcurrentMap<MessageQueue, ProcessQueue> mqTable = this.rebalanceImpl.getProcessQueueTable();
        Set<MessageQueue> mqResult = new HashSet<>();
        for (MessageQueue mq : mqTable.keySet()) {
            if (mq.getTopic().equals(topic)) {
                mqResult.add(mq);
            }
        }

        return parseSubscribeMessageQueues(mqResult);
    }

    public List<MessageQueue> fetchPublishMessageQueues(String topic) throws MQClientException {
        this.isRunning();
        return this.mQClientFactory.getMQAdminImpl().fetchPublishMessageQueues(topic);
    }

View on GitHub (pinned to 293f588571)

Solutions

1. Validate topic != null before the call
2. Centralize topic constants in one enum/constants class to avoid null propagation

Example fix

// before
Set<MessageQueue> qs = consumer.fetchMessageQueuesInBalance(topic);

// after
Objects.requireNonNull(topic, "topic");
Set<MessageQueue> qs = consumer.fetchMessageQueuesInBalance(topic);

Objects.requireNonNull(topic, "topic must not be null");
Set<MessageQueue> qs = consumer.fetchMessageQueuesInBalance(topic);

When it happens

Trigger: consumer.fetchMessageQueuesInBalance(null) on a started DefaultMQPullConsumer.

Common situations: Topic passed through several layers of code and lost; conditional assignment left the variable null.

Related errors

• consumerGroup can not equal
• Topic can not be null or empty.
• Message queues can not be null or empty.
• subExpression can not be null or empty.
• Timeout must not be negative

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