apache/rocketmq · error · MQClientException

create new topic failed

Error message

create new topic failed

What it means

The outer catch of MQAdminImpl.createTopic wraps any exception thrown during topic creation (including the inner 'Not found broker' error, remoting failures, or broker rejection) into MQClientException('create new topic failed'). The original cause is preserved in the exception chain, so e.getCause() holds the real failure.

Source

Thrown at client/src/main/java/org/apache/rocketmq/client/impl/MQAdminImpl.java:139

                        }

                        if (createOK) {
                            orderTopicString.append(brokerData.getBrokerName());
                            orderTopicString.append(":");
                            orderTopicString.append(queueNum);
                            orderTopicString.append(";");
                        }
                    }
                }

                if (exception != null && !createOKAtLeastOnce) {
                    throw exception;
                }
            } else {
                throw new MQClientException("Not found broker, maybe key is wrong", null);
            }
        } catch (Exception e) {
            throw new MQClientException("create new topic failed", e);
        }
    }

    public List<MessageQueue> fetchPublishMessageQueues(String topic) throws MQClientException {
        try {
            TopicRouteData topicRouteData = this.mQClientFactory.getMQClientAPIImpl().getTopicRouteInfoFromNameServer(topic, timeoutMillis);
            if (topicRouteData != null) {
                TopicPublishInfo topicPublishInfo = MQClientInstance.topicRouteData2TopicPublishInfo(topic, topicRouteData);
                if (topicPublishInfo != null && topicPublishInfo.ok()) {
                    return parsePublishMessageQueues(topicPublishInfo.getMessageQueueList());
                }
            }
        } catch (Exception e) {
            throw new MQClientException("Can not find Message Queue for this topic, " + topic, e);
        }

        throw new MQClientException("Unknown why, Can not find Message Queue for this topic, " + topic, null);
    }

View on GitHub (pinned to 293f588571)

Solutions

1. Inspect e.getCause() — it distinguishes 'not found broker' vs timeout vs broker-side rejection
2. Prefer mqadmin updateTopic -n <namesrv> -b <brokerAddr> -t <topic> for creation
3. Verify autoCreateTopicEnable or explicit create permission on the cluster
4. Confirm name server connectivity and topic config (queue counts, perms) are valid

try {
    mqAdmin.createTopic(key, topic, numQueues);
} catch (MQClientException e) {
    Throwable cause = e.getCause();
    log.error("createTopic failed: {}", cause == null ? e : cause);
    // branch on cause: not-found-broker vs timeout vs permission
}

When it happens

Trigger: Any client-side createTopic call that fails: no broker found for the key, name server timeout, broker returns an error for the create request, or insufficient permissions (TOPIC creation disabled, autoCreateTopicEnable=false).

Common situations: Auto-create disabled on brokers and the key/broker mapping wrong; network partition to name server; using a non-admin client without topic-creation permission.

Related errors

• Not found broker, maybe key is wrong
• Failed to get max offset in queue
• Failed to get max offset in queue
• Can not find Message Queue for this topic, ${topic}
• Unknown why, Can not find Message Queue for this topic, ${to

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