feat: dont throw on ENOENT if allowMissing is set

nodejs · nodejs-github-bot · Apr 10, 2026 · Feb 17, 2026 · Feb 18, 2026 · Feb 18, 2026
commit 82654419f68a6673525d80ce47410a490a866d23
diff --git a/lib/fs.js b/lib/fs.js
@@ -2488,6 +2488,7 @@ function appendFileSync(path, data, options) {
  *   recursive?: boolean;
  *   encoding?: string;
  *   signal?: AbortSignal;
+ *   throwIfNoEntry?: boolean;
  *   }} [options]
  * @param {(
  *   eventType?: string,
@@ -2506,6 +2507,7 @@ function watch(filename, options, listener) {
 
   if (options.persistent === undefined) options.persistent = true;
   if (options.recursive === undefined) options.recursive = false;
+  if (options.throwIfNoEntry === undefined) options.throwIfNoEntry = true;
 
   let watcher;
   const watchers = require('internal/fs/watchers');
@@ -2523,7 +2525,8 @@ function watch(filename, options, listener) {
                                     options.persistent,
                                     options.recursive,
                                     options.encoding,
-                                    options.ignore);
+                                    options.ignore,
+                                    options.throwIfNoEntry);
   }
 
   if (listener) {

diff --git a/lib/internal/fs/recursive_watch.js b/lib/internal/fs/recursive_watch.js
@@ -51,7 +51,7 @@ class FSWatcher extends EventEmitter {
 
     assert(typeof options === 'object');
 
-    const { persistent, recursive, signal, encoding, ignore } = options;
+    const { persistent, recursive, signal, encoding, ignore, throwIfNoEntry } = options;
 
     // TODO(anonrig): Add non-recursive support to non-native-watcher for IBMi & AIX support.
     if (recursive != null) {
@@ -66,6 +66,10 @@ class FSWatcher extends EventEmitter {
       validateAbortSignal(signal, 'options.signal');
     }
 
+    if (throwIfNoEntry != null) {
+      validateBoolean(throwIfNoEntry, 'options.throwIfNoEntry');
+    }
+
     if (encoding != null) {
       // This is required since on macOS and Windows it throws ERR_INVALID_ARG_VALUE
       if (typeof encoding !== 'string') {
@@ -76,7 +80,7 @@ class FSWatcher extends EventEmitter {
     validateIgnoreOption(ignore, 'options.ignore');
     this.#ignoreMatcher = createIgnoreMatcher(ignore);
 
-    this.#options = { persistent, recursive, signal, encoding };
+    this.#options = { persistent, recursive, signal, encoding, throwIfNoEntry };
   }
 
   close() {
@@ -222,7 +226,7 @@ class FSWatcher extends EventEmitter {
         this.#watchFolder(filename);
       }
     } catch (error) {
-      if (error.code === 'ENOENT') {
+      if (this.#options.throwIfNoEntry !== false && error.code === 'ENOENT') {
         error.filename = filename;
         throw error;
       }

diff --git a/lib/internal/fs/watchers.js b/lib/internal/fs/watchers.js
@@ -35,7 +35,7 @@ const {
 } = internalBinding('fs');
 
 const { FSEvent } = internalBinding('fs_event_wrap');
-const { UV_ENOSPC } = internalBinding('uv');
+const { UV_ENOSPC, UV_ENOENT } = internalBinding('uv');
 const { EventEmitter } = require('events');
 
 const {
@@ -293,7 +293,8 @@ FSWatcher.prototype[kFSWatchStart] = function(filename,
                                               persistent,
                                               recursive,
                                               encoding,
-                                              ignore) {
+                                              ignore,
+                                              throwIfNoEntry = true) {
   if (this._handle === null) {  // closed
     return;
   }
@@ -313,6 +314,10 @@ FSWatcher.prototype[kFSWatchStart] = function(filename,
                                  recursive,
                                  encoding);
   if (err) {
+    if (!throwIfNoEntry && err === UV_ENOENT) {
+      return;
+    }
+
     const error = new UVException({
       errno: err,
       syscall: 'watch',

diff --git a/lib/internal/main/watch_mode.js b/lib/internal/main/watch_mode.js
@@ -104,16 +104,7 @@
     ArrayPrototypeForEach(kEnvFiles, (file) => watcher.filterFile(resolve(file)));
   }
   if (kOptionalEnvFiles.length > 0) {
-    ArrayPrototypeForEach(kOptionalEnvFiles, (file) => {
-      try {
-        watcher.filterFile(resolve(file));
-      } catch (error) {
-        if (error?.code !== 'ENOENT' && error?.code !== 'ENOTDIR') {
-          throw error;
-        }
-        // Failed watching the file, ignore
-      }
-    });
+    ArrayPrototypeForEach(kOptionalEnvFiles, (file) =>  watcher.filterFile(resolve(file), undefined, true));
   }
   child.once('exit', (code) => {
     exited = true;

diff --git a/lib/internal/watch_mode/files_watcher.js b/lib/internal/watch_mode/files_watcher.js
@@ -110,11 +110,11 @@
     return [...this.#watchers.keys()];
   }
 
-  watchPath(path, recursive = true) {
+  watchPath(path, recursive = true, allowMissing = false) {
     if (this.#isPathWatched(path)) {
       return;
     }
-    const watcher = watch(path, { recursive, signal: this.#signal });
+    const watcher = watch(path, { recursive, signal: this.#signal, throwIfNoEntry: !allowMissing });
     watcher.on('change', (eventType, fileName) => {
       // `fileName` can be `null` if it cannot be determined. See
       // https://github.com/nodejs/node/pull/49891#issuecomment-1744673430.
@@ -126,14 +126,14 @@
     }
   }
 
-  filterFile(file, owner) {
+  filterFile(file, owner, allowMissing = false) {
     if (!file) return;
     if (supportsRecursiveWatching) {
-      this.watchPath(dirname(file));
+      this.watchPath(dirname(file),true, allowMissing);
     } else {
       // Having multiple FSWatcher's seems to be slower
       // than a single recursive FSWatcher
-      this.watchPath(file, false);
+      this.watchPath(file, false, allowMissing);
     }
     this.#filteredFiles.add(file);
     if (owner) {