{"record":{"id":"a422baaf89817c39","repo":"alibaba/spring-cloud-alibaba","slug":"configservice-not-available","errorCode":null,"errorMessage":"ConfigService not available","messagePattern":"ConfigService not available","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"critical","filePath":"spring-cloud-alibaba-starters/spring-alibaba-nacos-config/src/main/java/com/alibaba/cloud/nacos/refresh/NacosContextRefresher.java","lineNumber":149,"sourceCode":"\t\t\t\t\t\tevent.setDataId(dataId);\n\t\t\t\t\t\tevent.setGroup(group);\n\t\t\t\t\tif (applicationContext != null) {\n\t\t\t\t\t\tapplicationContext.publishEvent(\n\t\t\t\t\t\t\t\tevent);\n\t\t\t\t\t}\n\t\t\t\t\t\tif (log.isDebugEnabled()) {\n\t\t\t\t\t\t\tlog.debug(String.format(\n\t\t\t\t\t\t\t\t\t\"Publish Nacos config Refresh Event group=%s,dataId=%s,configInfo=%s\",\n\t\t\t\t\t\t\t\t\tgroup, dataId, configInfo));\n\t\t\t\t\t\t}\n\t\t\t\t\t}\n\t\t\t\t});\n\t\ttry {\n\t\t\tif (configService == null && configManager != null) {\n\t\t\t\tconfigService = configManager.getConfigService();\n\t\t\t}\n\t\t\tif (configService == null) {\n\t\t\t\tthrow new IllegalStateException(\"ConfigService not available\");\n\t\t\t}\n\t\t\tconfigService.addListener(dataKey, groupKey, listener);\n\t\t\tlog.info(\"[Nacos Config] Listening config: dataId={}, group={}\", dataKey,\n\t\t\t\t\tgroupKey);\n\t\t}\n\t\tcatch (NacosException e) {\n\t\t\tlog.warn(String.format(\n\t\t\t\t\t\"register fail for nacos listener ,dataId=[%s],group=[%s]\", dataKey,\n\t\t\t\t\tgroupKey), e);\n\t\t}\n\t}\n\n\tpublic NacosConfigProperties getNacosConfigProperties() {\n\t\treturn nacosConfigProperties;\n\t}\n\n\tpublic NacosContextRefresher setNacosConfigProperties(\n\t\t\tNacosConfigProperties nacosConfigProperties) {","sourceCodeStart":131,"sourceCodeEnd":167,"githubUrl":"https://github.com/alibaba/spring-cloud-alibaba/blob/115d5901102009492e05d5ec18c3f79cad4077d0/spring-cloud-alibaba-starters/spring-alibaba-nacos-config/src/main/java/com/alibaba/cloud/nacos/refresh/NacosContextRefresher.java#L131-L167","documentation":"Thrown inside NacosContextRefresher.registerNacosListener when it cannot obtain a non-null ConfigService instance. The refresher first checks its own nullable configService field; if null, it delegates to configManager.getConfigService(). If that also returns null, the IllegalStateException is thrown. Critically, the surrounding try-catch only catches NacosException, so this IllegalStateException is NOT swallowed — it propagates up through the ApplicationReadyEvent listener callback and fails application startup.","triggerScenarios":"ApplicationReadyEvent fires and registerNacosListenersForApplications iterates over NacosPropertySourceRepository entries. For each refreshable property source, registerNacosListener is called. If NacosConfigManager.getConfigService() returns null (typically because NacosConfigProperties did not successfully create a ConfigService — e.g., server-addr not set or Nacos client initialization failed silently), the null check at line 148 triggers.","commonSituations":"1) Nacos config server-addr is missing or wrong, causing ConfigService creation to fail internally without throwing during bootstrap. 2) Network connectivity to the Nacos server is broken at startup so the client cannot initialize. 3) NacosConfigProperties is misconfigured (e.g., namespace or access-key issues) so that getConfigService() returns null. 4) A custom NacosConfigManager that returns null from getConfigService().","solutions":["Verify spring.cloud.nacos.config.server-addr is set and the Nacos server is reachable at startup time.","Check NacosConfigProperties for correct namespace, username, password, and access-key configuration.","Ensure network connectivity / firewall rules allow the application to reach the Nacos server on the configured port.","If this occurs after a Nacos server outage, investigate whether the Nacos client SDK version in use has a known bug around ConfigService lazy initialization."],"exampleFix":"# before (broken — server-addr missing or wrong)\nspring:\n  cloud:\n    nacos:\n      config:\n        # server-addr omitted or incorrect\n\n# after (fixed)\nspring:\n  cloud:\n    nacos:\n      config:\n        server-addr: 127.0.0.1:8848","handlingStrategy":"validation","validationCode":"// Before relying on ConfigService, validate NacosConfigManager can produce one\n@Autowired(required = false)\nprivate NacosConfigManager configManager;\n\n@EventListener(ApplicationReadyEvent.class)\npublic void checkConfigService() {\n    if (configManager != null) {\n        ConfigService cs = configManager.getConfigService();\n        if (cs == null) {\n            log.error(\"Nacos ConfigService is null — check server-addr and network\");\n        }\n    }\n}","typeGuard":null,"tryCatchPattern":"// The framework's own catch only handles NacosException.\n// If calling registerNacosListener-like logic yourself:\ntry {\n    configService.addListener(dataId, group, listener);\n} catch (NacosException e) {\n    log.warn(\"Nacos listener registration failed for {}:{}\", dataId, group, e);\n} catch (IllegalStateException e) {\n    // ConfigService not available — check Nacos connectivity\n    log.error(\"Nacos ConfigService unavailable — verify server-addr and network\", e);\n    throw e;\n}","preventionTips":["Always set spring.cloud.nacos.config.server-addr in every environment.","Add a startup probe or health indicator that verifies Nacos server reachability before ApplicationReadyEvent.","Monitor NacosConfigManager.getConfigService() for null during integration tests.","Ensure Nacos client version is compatible with your Spring Cloud Alibaba version."],"tags":["nacos","config-service","spring-boot","startup","configuration","network"],"backgroundTag":null,"analyzedSha":"115d5901102009492e05d5ec18c3f79cad4077d0","analyzedAt":"2026-08-14T04:47:13.900Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}