{"record":{"id":"d567248b9c154be5","repo":"alibaba/nacos","slug":"501-d56724","errorCode":"501","errorMessage":"Request Nacos server version is too low, not support fuzzy watch feature.","messagePattern":"Request Nacos server version is too low, not support fuzzy watch feature\\.","errorType":"exception","errorClass":"NacosRuntimeException","httpStatus":null,"severity":"error","filePath":"client/src/main/java/com/alibaba/nacos/client/naming/cache/NamingFuzzyWatchServiceListHolder.java","lineNumber":149,"sourceCode":"    }\n    \n    public void registerNamingGrpcClientProxy(NamingGrpcClientProxy namingGrpcClientProxy) {\n        this.namingGrpcClientProxy = namingGrpcClientProxy;\n    }\n    \n    public NamingFuzzyWatchContext getFuzzyWatchContext(String groupKeyPattern) {\n        return fuzzyMatchContextMap.get(groupKeyPattern);\n    }\n    \n    /**\n     * Add a watcher to the context.\n     *\n     * @param watcher watcher to be added\n     */\n    public NamingFuzzyWatchContext registerFuzzyWatcher(String groupKeyPattern,\n        FuzzyWatchEventWatcher watcher) {\n        if (!namingGrpcClientProxy.isAbilitySupportedByServer(AbilityKey.SERVER_FUZZY_WATCH)) {\n            throw new NacosRuntimeException(NacosException.SERVER_NOT_IMPLEMENTED,\n                \"Request Nacos server version is too low, not support fuzzy watch feature.\");\n        }\n        NamingFuzzyWatchContext namingFuzzyWatchContext =\n            initFuzzyWatchContextIfNeed(groupKeyPattern);\n        namingFuzzyWatchContext.setDiscard(false);\n        synchronized (namingFuzzyWatchContext) {\n            FuzzyWatchEventWatcherWrapper fuzzyWatchEventWatcherWrapper =\n                new FuzzyWatchEventWatcherWrapper(watcher);\n            if (namingFuzzyWatchContext.getFuzzyWatchEventWatcherWrappers()\n                .add(fuzzyWatchEventWatcherWrapper)) {\n                LOGGER.info(\" [add-watcher-ok] groupKeyPattern={}, watcher={},uuid={} \",\n                    groupKeyPattern, watcher,\n                    fuzzyWatchEventWatcherWrapper.getUuid());\n                Set<String> receivedServiceKeys = namingFuzzyWatchContext.getReceivedServiceKeys();\n                if (CollectionUtils.isNotEmpty(receivedServiceKeys)) {\n                    for (String serviceKey : receivedServiceKeys) {\n                        NamingFuzzyWatchNotifyEvent namingFuzzyWatchNotifyEvent =\n                            NamingFuzzyWatchNotifyEvent.build(","sourceCodeStart":131,"sourceCodeEnd":167,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/client/src/main/java/com/alibaba/nacos/client/naming/cache/NamingFuzzyWatchServiceListHolder.java#L131-L167","documentation":"Thrown by NamingFuzzyWatchServiceListHolder.registerFuzzyWatcher when the naming gRPC client reports the server does not support SERVER_FUZZY_WATCH ability (code 501, SERVER_NOT_IMPLEMENTED). Fuzzy watch is a newer server feature; an old server cannot serve fuzzy-watch notifications. The check happens at registration time so an unsupported server fails fast rather than hanging on a future that never completes.","triggerScenarios":"Calling NamingService.fuzzyWatch or registerFuzzyWatcher against a Nacos server too old to support fuzzy watch; connecting to a mixed-version cluster node that lacks the feature; server built/disabled without fuzzy-watch support.","commonSituations":"Client SDK upgraded ahead of the server; legacy 2.x server; mixed cluster failover to an old node; server feature disabled by config.","solutions":["Upgrade the Nacos server to a version that supports fuzzy watch.","Catch NacosRuntimeException 501 and fall back to exact service subscriptions or polling.","Verify SERVER_FUZZY_WATCH ability at connection setup before offering fuzzy-watch functionality."],"exampleFix":"// before\nnaming.fuzzyWatch(groupKeyPattern, watcher); // throws 501 on old server\n\n// after\ntry {\n    naming.fuzzyWatch(groupKeyPattern, watcher);\n} catch (NacosRuntimeException e) {\n    if (e.getCode() == NacosException.SERVER_NOT_IMPLEMENTED) {\n        // fall back to per-service subscribe\n    } else { throw e; }\n}","handlingStrategy":"try-catch","validationCode":"if (namingGrpcClientProxy.isAbilitySupportedByServer(AbilityKey.SERVER_FUZZY_WATCH)) {\n    naming.fuzzyWatch(pattern, watcher);\n} else {\n    // fall back to exact subscriptions\n}","typeGuard":null,"tryCatchPattern":"try { naming.fuzzyWatch(pattern, watcher); } catch (NacosRuntimeException e) { if (e.getCode() == NacosException.SERVER_NOT_IMPLEMENTED) { /* fall back */ } else throw e; }","preventionTips":["Upgrade the server to support fuzzy watch.","Check SERVER_FUZZY_WATCH ability before offering fuzzy-watch UI.","Provide an exact-subscription fallback when fuzzy watch is unavailable."],"tags":["naming","fuzzy-watch","version-mismatch","ability-negotiation","server-not-implemented"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}