{"record":{"id":"52e371f25d730a16","repo":"alibaba/nacos","slug":"fuzzy-watch-result-future-timeout-for-millis","errorCode":null,"errorMessage":"fuzzy watch result future timeout for {} millis","messagePattern":"fuzzy watch result future timeout for (.+?) millis","errorType":"exception","errorClass":"TimeoutException","httpStatus":null,"severity":"warning","filePath":"client/src/main/java/com/alibaba/nacos/client/naming/cache/NamingFuzzyWatchContext.java","lineNumber":464,"sourceCode":"                ListView<String> result = new ListView<>();\n                result.setData(Arrays.asList(\n                    NamingFuzzyWatchContext.this.receivedServiceKeys.toArray(new String[0])));\n                result.setCount(result.getData().size());\n                return result;\n            }\n            \n            @Override\n            public ListView<String> get(long timeout, TimeUnit unit)\n                throws InterruptedException, TimeoutException {\n                \n                if (!NamingFuzzyWatchContext.this.initializationCompleted.get()) {\n                    synchronized (NamingFuzzyWatchContext.this) {\n                        NamingFuzzyWatchContext.this.wait(unit.toMillis(timeout));\n                    }\n                }\n                \n                if (!NamingFuzzyWatchContext.this.initializationCompleted.get()) {\n                    throw new TimeoutException(\n                        \"fuzzy watch result future timeout for \" + unit.toMillis(timeout)\n                            + \" millis\");\n                }\n                \n                ListView<String> result = new ListView<>();\n                result.setData(Arrays.asList(\n                    NamingFuzzyWatchContext.this.receivedServiceKeys.toArray(new String[0])));\n                result.setCount(result.getData().size());\n                return result;\n            }\n        };\n        return completableFuture;\n    }\n}\n","sourceCodeStart":446,"sourceCodeEnd":479,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/client/src/main/java/com/alibaba/nacos/client/naming/cache/NamingFuzzyWatchContext.java#L446-L479","documentation":"Thrown by the timed get(long, TimeUnit) of the fuzzy-watch Future when the context's initializationCompleted flag is still false after waiting the requested duration. The Future waits (Object.wait) for the server to finish the initial fuzzy-watch service-list sync; if that does not complete within the timeout, a standard java.util.concurrent.TimeoutException is raised.","triggerScenarios":"The server is slow to return the initial fuzzy-watch service list; the gRPC push of the initial batch is delayed or lost; the connection is unhealthy so the initialization handshake stalls; an unreasonably short timeout passed by the caller.","commonSituations":"Large service catalogs making the initial sync slow; network latency or packet loss on the gRPC stream; server under load; the pattern matches a very broad groupKeyPattern returning many services; caller-set timeouts that are too aggressive.","solutions":["Increase the timeout passed to future.get(timeout) to match expected sync latency.","Narrow the groupKeyPattern so fewer services match and the initial sync is faster.","Check naming client connection health and server load; ensure the gRPC stream is established.","Retry the fuzzy watch subscription if the stream appears stuck."],"exampleFix":"// before\nListView<String> keys = future.get(500, TimeUnit.MILLISECONDS); // often times out\n\n// after\nListView<String> keys = future.get(10, TimeUnit.SECONDS);","handlingStrategy":"retry","validationCode":"// Choose a timeout appropriate to expected sync latency and pattern breadth\nif (future.get(10, TimeUnit.SECONDS) == null) { /* still not ready */ }","typeGuard":null,"tryCatchPattern":"try { ListView<String> keys = future.get(timeout, unit); } catch (TimeoutException e) { // retry subscription or increase timeout LOGGER.warn(\"Fuzzy watch init timed out; retrying\", e); }","preventionTips":["Narrow the groupKeyPattern to reduce initial sync size.","Set a realistic timeout based on catalog size and network latency.","Verify gRPC connection health before relying on fast initialization."],"tags":["naming","fuzzy-watch","timeout","future","initialization"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}