remix-run/react-router · warning

File watcher error: ${message}

Error message

File watcher error: ${message}

What it means

In watch mode (`react-router dev`, or config watch subscribers), React Router watches the project root and app directory with chokidar. When the watcher emits an `error` event, the message is logged as a yellow `File watcher error: <message>` warning and watching continues in a degraded state — change-triggered restarts/rebuilds may silently stop firing until the watcher recovers or the process restarts. It never crashes the process by itself.

Source

Thrown at packages/react-router-dev/config/config.ts:885

    getConfig,
    onChange: (handler: ChangeHandler) => {
      if (!watch) {
        throw new Error(
          "onChange is not supported when watch mode is disabled",
        );
      }

      changeHandlers.push(handler);

      if (!fsWatcher) {
        fsWatcher = chokidar.watch([root, appDirectory], {
          ignoreInitial: true,
          ignored: (path) => isIgnoredByWatcher(path, { root, appDirectory }),
        });

        fsWatcher.on("error", (error: unknown) => {
          let message = error instanceof Error ? error.message : String(error);
          console.warn(colors.yellow(`File watcher error: ${message}`));
        });

        fsWatcher.on("all", async (...args) => {
          let [event, rawFilepath] = args;
          let filepath = Path.normalize(rawFilepath);

          let fileAddedOrRemoved = event === "add" || event === "unlink";

          let appFileAddedOrRemoved =
            fileAddedOrRemoved &&
            filepath.startsWith(Path.normalize(appDirectory));

          let rootRelativeFilepath = Path.relative(root, filepath);

          let configFileAddedOrRemoved =
            fileAddedOrRemoved &&
            isEntryFile("react-router.config", rootRelativeFilepath);

View on GitHub (pinned to 6beaca3952)

Solutions

1. Raise the OS watcher limits and restart: `sudo sysctl fs.inotify.max_user_watches=524288 fs.inotify.max_user_instances=1024` (persist in /etc/sysctl.conf); in Docker, set the same sysctls or run with enough inotify capacity
2. Restart `react-router dev` — the watcher is created lazily and a fresh process rebuilds it
3. Reduce the watched surface: keep the app under a leaner root; node_modules and ignored paths are already excluded by isIgnoredByWatcher, but huge unignored directories still cost watch handles
4. Read the exact <message> in the warning: EACCES points at permissions on a specific path, ENOSPC at limits — fix that path/limit accordingly

Example fix

# before (defaults, ENOSPC errors in dev)
fs.inotify.max_user_watches=8192

# after (/etc/sysctl.conf, then: sudo sysctl --system)
fs.inotify.max_user_watches=524288
fs.inotify.max_user_instances=1024

// pre-flight check before starting dev on Linux
import fs from "node:fs";
function checkInotifyBudget(needed = 100000) {
  if (process.platform !== "linux") return;
  let watches = Number(fs.readFileSync("/proc/sys/fs/inotify/max_user_watches", "utf8"));
  if (watches < needed) {
    throw new Error(`fs.inotify.max_user_watches=${watches} < ${needed}. Run: sudo sysctl fs.inotify.max_user_watches=${needed}`);
  }
}
checkInotifyBudget();

// the library already swallows the chokidar error event and logs it;
// wrap your own watcher usage (if any) the same way:
watcher.on("error", (err) => { log.warn(`watcher: ${err.message}`); scheduleWatcherRestart(); });

When it happens

Trigger: chokidar emits `error` during dev: ENOSPC when the OS inotify user-watches limit is exhausted (deep node_modules/project trees), EACCES/EPERM on a watched path, unsupported filesystems (NFS, some Docker volume mounts on macOS), or the watch handle being closed externally.

Common situations: Large monorepos on Linux with default fs.inotify.max_user_watches; dev containers and CI dockers with tight inotify limits; projects on network file systems; many simultaneous dev servers/watchers on one host.

Related errors

• ${reactRouterConfigFile} no longer exists
• The provided template is not a valid local directory or tarb
• File collisions detected in a non-interactive environment
• onChange is not supported when watch mode is disabled
• When using the React Router `basename` and the Vite `base` c

AI-assisted analysis of remix-run/react-router@6beaca3952 (2026-08-18). Data as JSON: /api/errors/725bbc728c9b7237. Report an issue: GitHub.