{"record":{"id":"d96c9933becb926c","repo":"alibaba/nacos","slug":"50310-d96c99","errorCode":"50310","errorMessage":"fuzzy watch pattern over limit","messagePattern":"fuzzy watch pattern over limit","errorType":"error_code","errorClass":"NacosException","httpStatus":null,"severity":"error","filePath":"naming/src/main/java/com/alibaba/nacos/naming/core/v2/index/NamingFuzzyWatchContextService.java","lineNumber":325,"sourceCode":"        if (clients != null) {\n            clients.remove(clientId);\n        }\n    }\n    \n    /**\n     * This method will build/update the fuzzy watch match index for given patterns.\n     *\n     * @param completedPattern the completed pattern of watch (with namespace id).\n     * @return a copy set of matched service keys in Nacos server\n     */\n    public Set<String> initWatchMatchService(String completedPattern) throws NacosException {\n        \n        if (!matchedServiceKeysMap.containsKey(completedPattern)) {\n            if (matchedServiceKeysMap.size() >= GlobalConfig.getMaxPatternCount()) {\n                Loggers.SRV_LOG.warn(\n                    \"FUZZY_WATCH: fuzzy watch pattern count is over limit ,pattern {} init fail,current count is {}\",\n                    completedPattern, matchedServiceKeysMap.size());\n                throw new NacosException(FUZZY_WATCH_PATTERN_OVER_LIMIT.getCode(),\n                    FUZZY_WATCH_PATTERN_OVER_LIMIT.getMsg());\n            }\n            \n            long matchBeginTime = System.currentTimeMillis();\n            Set<Service> namespaceServices = ServiceManager.getInstance()\n                .getSingletons(getNamespaceFromPattern(completedPattern));\n            Set<String> matchedServices =\n                matchedServiceKeysMap.computeIfAbsent(completedPattern, k -> new HashSet<>());\n            boolean overMatchCount = false;\n            for (Service service : namespaceServices) {\n                if (FuzzyGroupKeyPattern.matchPattern(completedPattern, service.getName(),\n                    service.getGroup(),\n                    service.getNamespace())) {\n                    if (matchedServices.size() >= GlobalConfig.getMaxMatchedServiceCount()) {\n                        \n                        Loggers.SRV_LOG.warn(\n                            \"[fuzzy-watch] pattern matched service count is over limit , \"\n                                + \"other services will stop notify for pattern {} ,current count is {}\",","sourceCodeStart":307,"sourceCodeEnd":343,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/naming/src/main/java/com/alibaba/nacos/naming/core/v2/index/NamingFuzzyWatchContextService.java#L307-L343","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Increase the limit via JVM property -Dnacos.naming.fuzzy.watch.max.pattern.count=<N> on the server.","Consolidate client patterns — reuse shared wildcard patterns instead of per-client unique ones.","Audit and remove stale fuzzy-watch subscriptions that are no longer needed."],"exampleFix":"# before — default limit 20\n# server startup\nsh startup.sh -m standalone\n\n# after — raise limit\n-Dnacos.naming.fuzzy.watch.max.pattern.count=100","handlingStrategy":"validation","validationCode":"// Client-side: estimate distinct patterns before subscribing\n// Server-side: raise the limit\n// In server JVM args:\n// -Dnacos.naming.fuzzy.watch.max.pattern.count=100\n\n// Before subscribing, consolidate patterns:\nint distinctPatterns = countDistinctPatterns(); // across all clients in namespace\nif (distinctPatterns >= GlobalConfig.getMaxPatternCount()) {\n    // consolidate or reject new pattern\n}","typeGuard":null,"tryCatchPattern":"try {\n    namingFuzzyWatchContextService.initWatchMatchService(completedPattern);\n} catch (NacosException e) {\n    if (e.getErrCode() == ErrorCode.FUZZY_WATCH_PATTERN_OVER_LIMIT.getCode()) {\n        // 50310 — too many patterns; consolidate or raise server limit\n    } else throw e;\n}","preventionTips":["Consolidate wildcard patterns across clients to share slots.","Monitor distinct pattern count and proactively raise the limit.","Remove stale fuzzy-watch subscriptions when services are decommissioned."],"tags":["naming","fuzzy-watch","over-limit","quota","configuration"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}