Why Some Instances Miss @RefreshScope Updates in Spring Cloud Alibaba + Nacos and How to Fix Them

Background of @RefreshScope

@RefreshScope

is a Spring Cloud Commons scope that marks beans for dynamic configuration reload. Beans are proxied; when a RefreshEvent is published the cached instance is destroyed and recreated with the latest values. Only properties injected via @Value or @ConfigurationProperties can be refreshed.

@RestController
@RefreshScope
public class ConfigController {
    @Value("${app.message:default}")
    private String message;
    @GetMapping("/msg")
    public String getMessage() { return message; }
}

@Component
@RefreshScope
@ConfigurationProperties(prefix = "app.settings")
public class AppSettings {
    private String name;
    private int timeout;
    // getters/setters
}

Nacos‑driven refresh chain

Nacos Server
  ↓ (long‑polling push)
Nacos Client (com.alibaba.nacos.client)
  ↓ (callback Listener)
NacosContextRefresher (Spring Cloud Alibaba)
  ↓ (publish RefreshEvent)
RefreshEventListener (Spring Cloud Commons)
  ↓ (call refreshAll())
RefreshScope
  ↓ (destroy cache, rebuild bean)
Your @RefreshScope bean → uses new config

The chain runs automatically; manual /actuator/refresh is only needed if auto‑refresh is disabled.

Root cause analysis

The key classes are NacosConfigProperties and NacosContextRefresher. In NacosConfigProperties each shared or extension config has a boolean refresh = false field. If refresh:true is not set, the config is not listened to.

public class NacosConfigProperties {
    public static class Config {
        private String dataId;
        private String group = "DEFAULT_GROUP";
        private boolean refresh = false; // default false!
    }
}

NacosContextRefresher

registers listeners only for configs whose refresh flag is true:

void registerNacosListenersForApplications() {
    for (Config config : properties.getSharedConfigs()) {
        if (config.isRefresh()) { // only when refresh=true
            registerNacosListener(config.getGroup(), config.getDataId());
        }
    }
    // same for extension-configs
}

Typical failure reasons

Missing refresh:true in bootstrap.yml for some instances.

Listener not registered due to startup errors or network issues.

Incorrect @RefreshScope usage : bean not annotated, static fields, or constructor injection.

Nacos client connection failure : long‑polling broken, no push.

Version incompatibility : older Spring Cloud Alibaba versions drop listeners; upgrade to 2021.1 or 2022.0.0.1.

Verification steps

Ensure every instance’s bootstrap.yml contains refresh:true for shared and extension configs.

spring:
  cloud:
    nacos:
      config:
        shared-configs:
        - data-id: common.yaml
          refresh: true
        extension-configs:
        - data-id: app-prod.yaml
          refresh: true

Check listener registration in the Nacos console (Configuration Management → Listener Query). All instance IPs should appear.

Enable DEBUG logging to see registration and event publishing:

logging:
  level:
    com.alibaba.nacos: DEBUG
    com.alibaba.cloud.nacos.refresh: DEBUG

Test bean recreation by exposing an endpoint that returns this.hashCode(). After a config change, the hash should change; if not, the bean was not refreshed.

Best‑practice recommendations

Explicitly set refresh:true for every shared or extension config that requires hot‑update.

Prefer @ConfigurationProperties over @Value for type safety and complex objects.

Avoid static fields for configuration values; they cannot be refreshed.

Monitor Nacos listener status and alert when an instance is missing.

Use stable version combinations, e.g.

Spring Boot 2.7.x + Spring Cloud 2021.0.x + Spring Cloud Alibaba 2021.1

Spring Boot 3.x + Spring Cloud 2022.0.x + Spring Cloud Alibaba 2022.0.0.1

For newer versions, enable auto‑refresh explicitly:

spring:
  cloud:
    nacos:
      config:
        refresh-enabled: true

Summary

Partial‑machine refresh failures are caused mainly by missing refresh:true, which prevents listener registration in NacosContextRefresher. Ensuring configuration consistency, successful listener registration, event publishing, and bean recreation guarantees true hot‑update of configuration across all instances.