apache/rocketmq · error · RuntimeException

The configuration item NamesrvAddr is not configured

Error message

The configuration item NamesrvAddr is not configured

What it means

A RuntimeException thrown from MQClientAPIFactory.init() when neither namesrvDomain nor namesrvAddr is set on the NameserverAccessConfig. The factory cannot build a remoting client without at least one way to discover the name server, so it fails fast at construction time (unlike most RocketMQ errors this is a plain RuntimeException, not MQClientException). It is commonly hit in the 5.x gRPC/IPC client wrappers that build an MQClientAPIFactory internally.

Source

Thrown at client/src/main/java/org/apache/rocketmq/client/impl/mqclient/MQClientAPIFactory.java:82

        ScheduledExecutorService scheduledExecutorService,
        ObjectCreator<RemotingClient> remotingClientCreator
    ) {
        this.nameserverAccessConfig = nameserverAccessConfig;
        this.namePrefix = namePrefix;
        this.clientNum = clientNum;
        this.clientRemotingProcessor = clientRemotingProcessor;
        this.rpcHook = rpcHook;
        this.scheduledExecutorService = scheduledExecutorService;
        this.remotingClientCreator = remotingClientCreator;

        this.init();
    }

    protected void init() {
        System.setProperty(ClientConfig.SEND_MESSAGE_WITH_VIP_CHANNEL_PROPERTY, "false");
        if (StringUtils.isEmpty(nameserverAccessConfig.getNamesrvDomain())) {
            if (Strings.isNullOrEmpty(nameserverAccessConfig.getNamesrvAddr())) {
                throw new RuntimeException("The configuration item NamesrvAddr is not configured");
            }
            System.setProperty(MixAll.NAMESRV_ADDR_PROPERTY, nameserverAccessConfig.getNamesrvAddr());
        } else {
            System.setProperty("rocketmq.namesrv.domain", nameserverAccessConfig.getNamesrvDomain());
            System.setProperty("rocketmq.namesrv.domain.subgroup", nameserverAccessConfig.getNamesrvDomainSubgroup());
        }
    }

    public MQClientAPIExt getClient() {
        if (clients.length == 1) {
            return this.clients[0];
        }
        int index = ThreadLocalRandom.current().nextInt(this.clients.length);
        return this.clients[index];
    }

    @Override
    public void start() throws Exception {

View on GitHub (pinned to 293f588571)

Solutions

Set the nameserver address explicitly: config.setNamesrvAddr("127.0.0.1:9876") or pass it via the constructor/builder
If using domain-based addressing, set namesrvDomain (and optionally namesrvDomainSubgroup) instead of namesrvAddr
If config comes from a file, verify it was actually loaded (log the NameserverAccessConfig values before creating the factory)
Set the JVM/system property rocketmq.namesrv.addr as a fallback before the client is built

Example fix

// before
NameserverAccessConfig cfg = new NameserverAccessConfig();
new MQClientAPIFactory("factory", clientId, cfg, hook, scheduler, creator); // throws
// after
NameserverAccessConfig cfg = new NameserverAccessConfig();
cfg.setNamesrvAddr("10.0.0.1:9876;10.0.0.2:9876");
new MQClientAPIFactory("factory", clientId, cfg, hook, scheduler, creator);

Defensive patterns

Strategy: validation

Validate before calling

 NameserverAccessConfig cfg = new NameserverAccessConfig();
cfg.setNamesrvAddr(nsAddr); // or cfg.setNamesrvDomain(domain)
if (Strings.isNullOrEmpty(cfg.getNamesrvAddr()) && Strings.isNullOrEmpty(cfg.getNamesrvDomain())) {
    throw new IllegalStateException("Configure namesrvAddr or namesrvDomain before building the client factory");
}

Try / catch

try {
    factory = new MQClientAPIFactory(...);
} catch (RuntimeException e) {
    if (e.getMessage().contains("NamesrvAddr is not configured")) {
        throw new ConfigurationException("RocketMQ name server missing - set NAMESRV_ADDR or rocketmq.namesrv.addr", e);
    }
    throw e;
}

Prevention

Fail fast in your bootstrap: assert nameserver config is non-empty before building any RocketMQ client
Externalize the nameserver (env NAMESRV_ADDR or -Drocketmq.namesrv.addr=...) and document it in the runbook
Add a startup config sanity check to CI smoke tests that instantiates the client
Distinguish address vs domain mode explicitly in config schemas so one is always required

When it happens

Trigger: Constructing an MQClientAPIFactory (directly or via a client wrapper such as the 5.x client or a spring-boot-starter) where NameserverAccessConfig has null/empty getNamesrvAddr() AND null/empty getNamesrvDomain(). Setting only the subGroup without the domain, or forgetting to pass the nameserver into the config object, triggers it in the constructor call to init().

Common situations: Migrating from the 4.x client (where the system property rocketmq.namesrv.addr was enough) to a wrapper that requires explicit config; typos in setter names like setNamesrvDomain; YAML/properties config file not loaded so the nameserver property is null; using the addressing-by-domain feature but leaving the domain blank in the environment.

Related errors

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