{"record":{"id":"1232a12ce79758f2","repo":"apache/rocketmq","slug":"the-configuration-item-namesrvaddr-is-not-configur","errorCode":null,"errorMessage":"The configuration item NamesrvAddr is not configured","messagePattern":"The configuration item NamesrvAddr is not configured","errorType":"validation","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"client/src/main/java/org/apache/rocketmq/client/impl/mqclient/MQClientAPIFactory.java","lineNumber":82,"sourceCode":"        ScheduledExecutorService scheduledExecutorService,\n        ObjectCreator<RemotingClient> remotingClientCreator\n    ) {\n        this.nameserverAccessConfig = nameserverAccessConfig;\n        this.namePrefix = namePrefix;\n        this.clientNum = clientNum;\n        this.clientRemotingProcessor = clientRemotingProcessor;\n        this.rpcHook = rpcHook;\n        this.scheduledExecutorService = scheduledExecutorService;\n        this.remotingClientCreator = remotingClientCreator;\n\n        this.init();\n    }\n\n    protected void init() {\n        System.setProperty(ClientConfig.SEND_MESSAGE_WITH_VIP_CHANNEL_PROPERTY, \"false\");\n        if (StringUtils.isEmpty(nameserverAccessConfig.getNamesrvDomain())) {\n            if (Strings.isNullOrEmpty(nameserverAccessConfig.getNamesrvAddr())) {\n                throw new RuntimeException(\"The configuration item NamesrvAddr is not configured\");\n            }\n            System.setProperty(MixAll.NAMESRV_ADDR_PROPERTY, nameserverAccessConfig.getNamesrvAddr());\n        } else {\n            System.setProperty(\"rocketmq.namesrv.domain\", nameserverAccessConfig.getNamesrvDomain());\n            System.setProperty(\"rocketmq.namesrv.domain.subgroup\", nameserverAccessConfig.getNamesrvDomainSubgroup());\n        }\n    }\n\n    public MQClientAPIExt getClient() {\n        if (clients.length == 1) {\n            return this.clients[0];\n        }\n        int index = ThreadLocalRandom.current().nextInt(this.clients.length);\n        return this.clients[index];\n    }\n\n    @Override\n    public void start() throws Exception {","sourceCodeStart":64,"sourceCodeEnd":100,"githubUrl":"https://github.com/apache/rocketmq/blob/293f5885719fc4aa3619446a1900f58ccfcfdd29/client/src/main/java/org/apache/rocketmq/client/impl/mqclient/MQClientAPIFactory.java#L64-L100","documentation":"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.","triggerScenarios":"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().","commonSituations":"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.","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"],"exampleFix":"// before\nNameserverAccessConfig cfg = new NameserverAccessConfig();\nnew MQClientAPIFactory(\"factory\", clientId, cfg, hook, scheduler, creator); // throws\n// after\nNameserverAccessConfig cfg = new NameserverAccessConfig();\ncfg.setNamesrvAddr(\"10.0.0.1:9876;10.0.0.2:9876\");\nnew MQClientAPIFactory(\"factory\", clientId, cfg, hook, scheduler, creator);","handlingStrategy":"validation","validationCode":" NameserverAccessConfig cfg = new NameserverAccessConfig();\ncfg.setNamesrvAddr(nsAddr); // or cfg.setNamesrvDomain(domain)\nif (Strings.isNullOrEmpty(cfg.getNamesrvAddr()) && Strings.isNullOrEmpty(cfg.getNamesrvDomain())) {\n    throw new IllegalStateException(\"Configure namesrvAddr or namesrvDomain before building the client factory\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    factory = new MQClientAPIFactory(...);\n} catch (RuntimeException e) {\n    if (e.getMessage().contains(\"NamesrvAddr is not configured\")) {\n        throw new ConfigurationException(\"RocketMQ name server missing - set NAMESRV_ADDR or rocketmq.namesrv.addr\", e);\n    }\n    throw e;\n}","preventionTips":["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"],"tags":["rocketmq","configuration","nameserver","startup"],"backgroundTag":null,"analyzedSha":"293f5885719fc4aa3619446a1900f58ccfcfdd29","analyzedAt":"2026-08-14T11:50:13.822Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}