alibaba/spring-cloud-alibaba · critical · IllegalStateException

ConfigService not available

Error message

ConfigService not available

What it means

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.

Source

Thrown at spring-cloud-alibaba-starters/spring-alibaba-nacos-config/src/main/java/com/alibaba/cloud/nacos/refresh/NacosContextRefresher.java:149

						event.setDataId(dataId);
						event.setGroup(group);
					if (applicationContext != null) {
						applicationContext.publishEvent(
								event);
					}
						if (log.isDebugEnabled()) {
							log.debug(String.format(
									"Publish Nacos config Refresh Event group=%s,dataId=%s,configInfo=%s",
									group, dataId, configInfo));
						}
					}
				});
		try {
			if (configService == null && configManager != null) {
				configService = configManager.getConfigService();
			}
			if (configService == null) {
				throw new IllegalStateException("ConfigService not available");
			}
			configService.addListener(dataKey, groupKey, listener);
			log.info("[Nacos Config] Listening config: dataId={}, group={}", dataKey,
					groupKey);
		}
		catch (NacosException e) {
			log.warn(String.format(
					"register fail for nacos listener ,dataId=[%s],group=[%s]", dataKey,
					groupKey), e);
		}
	}

	public NacosConfigProperties getNacosConfigProperties() {
		return nacosConfigProperties;
	}

	public NacosContextRefresher setNacosConfigProperties(
			NacosConfigProperties nacosConfigProperties) {

View on GitHub (pinned to 115d590110)

Solutions

1. Verify spring.cloud.nacos.config.server-addr is set and the Nacos server is reachable at startup time.
2. Check NacosConfigProperties for correct namespace, username, password, and access-key configuration.
3. Ensure network connectivity / firewall rules allow the application to reach the Nacos server on the configured port.
4. 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.

Example fix

# before (broken — server-addr missing or wrong)
spring:
  cloud:
    nacos:
      config:
        # server-addr omitted or incorrect

# after (fixed)
spring:
  cloud:
    nacos:
      config:
        server-addr: 127.0.0.1:8848

// Before relying on ConfigService, validate NacosConfigManager can produce one
@Autowired(required = false)
private NacosConfigManager configManager;

@EventListener(ApplicationReadyEvent.class)
public void checkConfigService() {
    if (configManager != null) {
        ConfigService cs = configManager.getConfigService();
        if (cs == null) {
            log.error("Nacos ConfigService is null — check server-addr and network");
        }
    }
}

// The framework's own catch only handles NacosException.
// If calling registerNacosListener-like logic yourself:
try {
    configService.addListener(dataId, group, listener);
} catch (NacosException e) {
    log.warn("Nacos listener registration failed for {}:{}", dataId, group, e);
} catch (IllegalStateException e) {
    // ConfigService not available — check Nacos connectivity
    log.error("Nacos ConfigService unavailable — verify server-addr and network", e);
    throw e;
}

When it happens

Trigger: 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.

Common situations: 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().

Related errors

• spring.nacos.config.proxy.druid.data-id is required
• NacosConfigManager not available
• NacosConfigProperties not available
• ConfigService is not initialized
• Binder not available in BootstrapContext

AI-assisted analysis of alibaba/spring-cloud-alibaba@115d590110 (2026-08-14). Data as JSON: /api/errors/a422baaf89817c39. Report an issue: GitHub.