alibaba/nacos · error · NacosException

50310

50310

Error message

fuzzy watch pattern over limit

What it means

Thrown by NamingFuzzyWatchContextService.initWatchMatchService when the number of distinct completed fuzzy-watch patterns in matchedServiceKeysMap reaches or exceeds GlobalConfig.getMaxPatternCount() (default 20, configurable via nacos.naming.fuzzy.watch.max.pattern.count). Error code 50310 maps to ErrorCode.FUZZY_WATCH_PATTERN_OVER_LIMIT. Each unique pattern (with namespace) consumes one slot; once the cap is hit, new patterns are rejected.

Source

Thrown at naming/src/main/java/com/alibaba/nacos/naming/core/v2/index/NamingFuzzyWatchContextService.java:325

        if (clients != null) {
            clients.remove(clientId);
        }
    }
    
    /**
     * This method will build/update the fuzzy watch match index for given patterns.
     *
     * @param completedPattern the completed pattern of watch (with namespace id).
     * @return a copy set of matched service keys in Nacos server
     */
    public Set<String> initWatchMatchService(String completedPattern) throws NacosException {
        
        if (!matchedServiceKeysMap.containsKey(completedPattern)) {
            if (matchedServiceKeysMap.size() >= GlobalConfig.getMaxPatternCount()) {
                Loggers.SRV_LOG.warn(
                    "FUZZY_WATCH: fuzzy watch pattern count is over limit ,pattern {} init fail,current count is {}",
                    completedPattern, matchedServiceKeysMap.size());
                throw new NacosException(FUZZY_WATCH_PATTERN_OVER_LIMIT.getCode(),
                    FUZZY_WATCH_PATTERN_OVER_LIMIT.getMsg());
            }
            
            long matchBeginTime = System.currentTimeMillis();
            Set<Service> namespaceServices = ServiceManager.getInstance()
                .getSingletons(getNamespaceFromPattern(completedPattern));
            Set<String> matchedServices =
                matchedServiceKeysMap.computeIfAbsent(completedPattern, k -> new HashSet<>());
            boolean overMatchCount = false;
            for (Service service : namespaceServices) {
                if (FuzzyGroupKeyPattern.matchPattern(completedPattern, service.getName(),
                    service.getGroup(),
                    service.getNamespace())) {
                    if (matchedServices.size() >= GlobalConfig.getMaxMatchedServiceCount()) {
                        
                        Loggers.SRV_LOG.warn(
                            "[fuzzy-watch] pattern matched service count is over limit , "
                                + "other services will stop notify for pattern {} ,current count is {}",

View on GitHub (pinned to 9b989acdf1)

Solutions

  1. Increase the limit via JVM property -Dnacos.naming.fuzzy.watch.max.pattern.count=<N> on the server.
  2. Consolidate client patterns — reuse shared wildcard patterns instead of per-client unique ones.
  3. Audit and remove stale fuzzy-watch subscriptions that are no longer needed.

Example fix

# before — default limit 20
# server startup
sh startup.sh -m standalone

# after — raise limit
-Dnacos.naming.fuzzy.watch.max.pattern.count=100
Defensive patterns

Strategy: validation

Validate before calling

// Client-side: estimate distinct patterns before subscribing
// Server-side: raise the limit
// In server JVM args:
// -Dnacos.naming.fuzzy.watch.max.pattern.count=100

// Before subscribing, consolidate patterns:
int distinctPatterns = countDistinctPatterns(); // across all clients in namespace
if (distinctPatterns >= GlobalConfig.getMaxPatternCount()) {
    // consolidate or reject new pattern
}

Try / catch

try {
    namingFuzzyWatchContextService.initWatchMatchService(completedPattern);
} catch (NacosException e) {
    if (e.getErrCode() == ErrorCode.FUZZY_WATCH_PATTERN_OVER_LIMIT.getCode()) {
        // 50310 — too many patterns; consolidate or raise server limit
    } else throw e;
}

Prevention

When it happens

Trigger: A client subscribes to a new fuzzy-watch pattern (e.g. 'DEFAULT_GROUP@@service-*') and the server already tracks 20 distinct patterns across all clients in that namespace. Each unique pattern string counts once regardless of how many clients watch it.

Common situations: Many microservices each using unique wildcard patterns for service discovery. Dynamic environment generation creating many pattern variants. Default limit of 20 is too low for large-scale deployments. Pattern strings differ only slightly (e.g. trailing whitespace) causing distinct entries.

Related errors

AI-assisted analysis of alibaba/nacos@9b989acdf1 (2026-08-14). Data as JSON: /api/errors/d96c9933becb926c. Report an issue: GitHub.