{"record":{"id":"f272c965f0ff6bf6","repo":"alibaba/nacos","slug":"must-be-a-file-directory","errorCode":null,"errorMessage":"Must be a file directory : ","messagePattern":"Must be a file directory : ","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"sys/src/main/java/com/alibaba/nacos/sys/file/WatchFileCenter.java","lineNumber":180,"sourceCode":"        \n        private final ExecutorService callBackExecutor;\n        \n        private final String paths;\n        \n        private final WatchService watchService;\n        \n        private volatile boolean watch = true;\n        \n        private final Set<FileWatcher> watchers = new ConcurrentHashSet<>();\n        \n        public WatchDirJob(String paths) throws NacosException {\n            // in aot process all threads must be daemon threads\n            setDaemon(true);\n            setName(paths);\n            this.paths = paths;\n            final Path p = Paths.get(paths);\n            if (!p.toFile().isDirectory()) {\n                throw new IllegalArgumentException(\"Must be a file directory : \" + paths);\n            }\n            \n            this.callBackExecutor = ExecutorFactory.newSingleExecutorService(\n                new NameThreadFactory(\"com.alibaba.nacos.sys.file.watch-\" + paths));\n            \n            try {\n                WatchService service = FILE_SYSTEM.newWatchService();\n                p.register(service, StandardWatchEventKinds.OVERFLOW,\n                    StandardWatchEventKinds.ENTRY_MODIFY,\n                    StandardWatchEventKinds.ENTRY_CREATE, StandardWatchEventKinds.ENTRY_DELETE);\n                this.watchService = service;\n            } catch (Throwable ex) {\n                throw new NacosException(NacosException.SERVER_ERROR, ex);\n            }\n        }\n        \n        void addSubscribe(final FileWatcher watcher) {\n            watchers.add(watcher);","sourceCodeStart":162,"sourceCodeEnd":198,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/sys/src/main/java/com/alibaba/nacos/sys/file/WatchFileCenter.java#L162-L198","documentation":"Thrown by WatchFileCenter's WatchDirJob constructor when the path passed to register a watcher is not an existing directory. The file watcher only monitors directories, so a file path or non-existent path is rejected.","triggerScenarios":"WatchFileCenter.registerWatcher(path, watcher) or the WatchDirJob is constructed with a path whose File.isDirectory() is false — the path points to a regular file, does not exist, or is a broken symlink.","commonSituations":"A config property for a watch directory points at a file (e.g. the conf file itself instead of the conf/ dir); the directory has not been created yet at startup; a typo in the path; the path is a symlink to a missing target.","solutions":["Correct the configured path to point at an existing directory.","Ensure the directory is created before the watcher is registered (create it during bootstrap).","Verify the path exists and is readable by the Nacos process user.","Check for typos and resolve any broken symlinks.","If the path is legitimately optional, guard registration behind an existence check."],"exampleFix":"// before\nWatchFileCenter.registerWatcher(\"/data/nacos/conf/application.properties\", watcher);\n\n// after\nPath dir = Paths.get(\"/data/nacos/conf\");\nFiles.createDirectories(dir);\nWatchFileCenter.registerWatcher(dir.toString(), watcher);","handlingStrategy":"validation","validationCode":"Path p = Paths.get(configuredPath);\nif (!Files.isDirectory(p)) {\n    throw new IllegalArgumentException(\"Not a directory: \" + configuredPath);\n}\nWatchFileCenter.registerWatcher(configuredPath, watcher);","typeGuard":null,"tryCatchPattern":"try {\n    WatchFileCenter.registerWatcher(path, watcher);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage() != null && e.getMessage().startsWith(\"Must be a file directory\")) {\n        // create dir or correct path, then retry\n    }\n    throw e;\n}","preventionTips":["Point watch paths at directories, not files.","Create directories during bootstrap before registering watchers.","Validate watch paths against Files.isDirectory at startup."],"tags":["sys","file-watch","configuration","startup"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}