Why Does Spring Cloud Gateway Return 404 After Nacos Config Changes?

Problem Description

Colleague used Spring Cloud Gateway 3.0.1 with JDK8 and integrated Nacos for dynamic routing. After modifying Nacos route configuration, the gateway returned 404 errors until it was restarted.

Environment Setup

Three backend services on ports 8103, 12040, 12041 were registered in Nacos with IDs xiaofu-8103, xiaofu-12040, xiaofu-12041 and placed in the same weight group xiaofu-group.

- id: xiaofu-8103
  uri: http://127.0.0.1:8103/
  predicates:
    - Weight=xiaofu-group, 2
    - Path=/test/version1/**
  filters:
    - RewritePath=/test/version1/(?<segment>.*),/${segment}
- id: xiaofu-12040
  uri: http://127.0.0.1:12040/
  predicates:
    - Weight=xiaofu-group, 1
    - Path=/test/version1/**
  filters:
    - RewritePath=/test/version1/(?<segment>.*),/${segment}
- id: xiaofu-12041
  uri: http://127.0.0.1:12041/
  predicates:
    - Weight=xiaofu-group, 2
    - Path=/test/version1/**
  filters:
    - RewritePath=/test/version1/(?<segment>.*),/${segment>

JMeter was used to send continuous requests with random parameters for traceability. All three instances logged requests, confirming load‑balancing worked.

Investigation

Log level was set to TRACE. After randomly changing URI, port, predicates and filters in Nacos, the gateway displayed updated routes without errors. Removing instance xiaofu-12041 caused JMeter to start returning 404, reproducing the issue.

Log inspection showed that the deleted instance’s route configuration still existed in the gateway cache and was still chosen for handling requests.

The root cause was that Nacos deletion removed the route from the configuration, but the gateway kept using stale weight data stored in a private groupWeights map.

Source Code Analysis

The WeightCalculatorWebFilter maintains a groupWeights variable. When a configuration change event occurs, it calls addWeightConfig(WeightConfig weightConfig), which only creates a new GroupWeightConfig and never removes old entries.

@Override
public void onApplicationEvent(ApplicationEvent event) {
    if (event instanceof PredicateArgsEvent) {
        handle((PredicateArgsEvent) event);
    } else if (event instanceof WeightDefinedEvent) {
        addWeightConfig(((WeightDefinedEvent) event).getWeightConfig());
    } else if (event instanceof RefreshRoutesEvent && routeLocator != null) {
        // refresh logic...
    }
}

This means deleted routes remain in the weight cache, leading to 404 errors.

Solution

Upgrading Spring Cloud Gateway to 4.1.0 did not fix the problem. The final fix is to listen for Nacos route‑refresh events, read the latest route definitions, and synchronize the groupWeights cache accordingly.

@Slf4j
@Configuration
public class WeightCacheRefresher {

    @Autowired
    private WeightCalculatorWebFilter weightCalculatorWebFilter;

    @Autowired
    private RouteDefinitionLocator routeDefinitionLocator;

    @EventListener(RefreshRoutesEvent.class)
    public void onRefreshRoutes() {
        log.info("Detected route refresh event, syncing weight cache");
        syncWeightCache();
    }

    public void syncWeightCache() {
        try {
            Field groupWeightsField = WeightCalculatorWebFilter.class.getDeclaredField("groupWeights");
            groupWeightsField.setAccessible(true);
            @SuppressWarnings("unchecked")
            Map<String, Object> groupWeights = (Map<String, Object>) groupWeightsField.get(weightCalculatorWebFilter);
            if (groupWeights == null) {
                log.warn("groupWeights cache not found");
                return;
            }
            // collect current route ids and weights
            Set<String> currentRouteIds = new HashSet<>();
            Map<String, Map<String, Integer>> currentGroupRouteWeights = new HashMap<>();
            routeDefinitionLocator.getRouteDefinitions()
                .collectList()
                .subscribe(definitions -> {
                    definitions.forEach(def -> {
                        currentRouteIds.add(def.getId());
                        def.getPredicates().stream()
                            .filter(p -> p.getName().equals("Weight"))
                            .forEach(p -> {
                                Map<String, String> args = p.getArgs();
                                String group = args.getOrDefault("_genkey_0", "unknown");
                                int weight = Integer.parseInt(args.getOrDefault("_genkey_1", "0"));
                                currentGroupRouteWeights.computeIfAbsent(group, k -> new HashMap<>())
                                    .put(def.getId(), weight);
                            });
                    });
                    // compare and update groupWeights (logic omitted for brevity)
                });
        } catch (Exception e) {
            log.error("Failed to sync weight cache", e);
        }
    }
}

After deploying this listener, any Nacos route change triggers a cache refresh, eliminating the stale‑weight 404 problem.

Conclusion

The bug originates from the gateway’s weight cache not being cleared when routes are removed. By manually synchronizing the cache on refresh events, the gateway always uses up‑to‑date routing information.