alibaba/nacos · error · IllegalArgumentException

Must be a file directory :

Error message

Must be a file directory : 

What it means

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.

Source

Thrown at sys/src/main/java/com/alibaba/nacos/sys/file/WatchFileCenter.java:180

        
        private final ExecutorService callBackExecutor;
        
        private final String paths;
        
        private final WatchService watchService;
        
        private volatile boolean watch = true;
        
        private final Set<FileWatcher> watchers = new ConcurrentHashSet<>();
        
        public WatchDirJob(String paths) throws NacosException {
            // in aot process all threads must be daemon threads
            setDaemon(true);
            setName(paths);
            this.paths = paths;
            final Path p = Paths.get(paths);
            if (!p.toFile().isDirectory()) {
                throw new IllegalArgumentException("Must be a file directory : " + paths);
            }
            
            this.callBackExecutor = ExecutorFactory.newSingleExecutorService(
                new NameThreadFactory("com.alibaba.nacos.sys.file.watch-" + paths));
            
            try {
                WatchService service = FILE_SYSTEM.newWatchService();
                p.register(service, StandardWatchEventKinds.OVERFLOW,
                    StandardWatchEventKinds.ENTRY_MODIFY,
                    StandardWatchEventKinds.ENTRY_CREATE, StandardWatchEventKinds.ENTRY_DELETE);
                this.watchService = service;
            } catch (Throwable ex) {
                throw new NacosException(NacosException.SERVER_ERROR, ex);
            }
        }
        
        void addSubscribe(final FileWatcher watcher) {
            watchers.add(watcher);

View on GitHub (pinned to 9b989acdf1)

Solutions

1. Correct the configured path to point at an existing directory.
2. Ensure the directory is created before the watcher is registered (create it during bootstrap).
3. Verify the path exists and is readable by the Nacos process user.
4. Check for typos and resolve any broken symlinks.
5. If the path is legitimately optional, guard registration behind an existence check.

Example fix

// before
WatchFileCenter.registerWatcher("/data/nacos/conf/application.properties", watcher);

// after
Path dir = Paths.get("/data/nacos/conf");
Files.createDirectories(dir);
WatchFileCenter.registerWatcher(dir.toString(), watcher);

Path p = Paths.get(configuredPath);
if (!Files.isDirectory(p)) {
    throw new IllegalArgumentException("Not a directory: " + configuredPath);
}
WatchFileCenter.registerWatcher(configuredPath, watcher);

try {
    WatchFileCenter.registerWatcher(path, watcher);
} catch (IllegalArgumentException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("Must be a file directory")) {
        // create dir or correct path, then retry
    }
    throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• processors multiple must upper than 1
• processors scale must between 0 and 1
• nacos address
• serverList is empty,please check configuration
• 400

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