Diagnosing nodemon Not Restarting on File Changes

Recognizable condition

nodemon starts the application successfully, but after editing a source file the process continues to run with the old code. No restart message appears in the console and the application behavior does not reflect the changes.

Cause and diagnostic table

Possible cause	What to look for
File extension not covered by --ext or nodemon.json ext	Edited file has a suffix that nodemon does not watch (e.g., .jsx when only js is configured).
Overly broad --ignore pattern	Ignore rules match the edited file, silencing the watch event.
Legacy watch required (no inotify)	Running inside Docker, WSL1, or on a filesystem that does not propagate inotify events.
--exec spawns a detached process	The command uses shell operators (;, &&, ||) or backgrounding (&) so nodemon cannot track the child PID.
Symlinks or mount options suppress events	The watched directory is a symlink or a volume mounted with options that block event forwarding.
Old nodemon version (<2.0)	Missing newer watch improvements that handle certain edge cases.

Ordered checks

1. Check nodemon version

   nodemon --version

   Record the output; versions <2.0.0 may lack recent watch fixes.
2. List watched paths with verbose output

   nodemon --verbose

   Look for lines like [nodemon] watching: /project/src/**/* and note any ignored entries.
3. Review configuration Examine nodemon.json or the command line for --ext, --ignore, --legacy-watch, and --exec flags.
4. Confirm file matches watched criteria Verify that the edited file’s extension is in the ext list and that its path is not excluded by any ignore pattern.
5. Test OS‑level file‑change delivery On Linux, run in a separate terminal:

   inotifywait -m -e close_write /path/to/watched/dir

   Edit the file and see if an event appears. No event indicates the host filesystem is not forwarding changes (common in Docker/WSL).
6. Inspect volume/mount settings For Docker, check the docker run or docker-compose mount: options like :ro or missing :cached/:delegated can suppress events. For WSL1, note that interop file‑system watching is limited; consider using WSL2 or enabling polling.

Fixes tied to findings

Configuration issues

• Add missing extensions: nodemon --ext js,ts,jsx or in nodemon.json set "ext": "js,ts,jsx".
• Refine or remove overly broad --ignore patterns. Replace --ignore * with specific paths, e.g., --ignore node_modules/.
• Enable legacy watch when inotify is unavailable: nodemon --legacy-watch or "legacyWatch": true in the config.

Environment and exec issues

• In Docker/WSL, activate polling: nodemon --pollingInterval 1000 (milliseconds). Adjust the interval if CPU usage becomes a concern.
• Ensure the --exec command returns a process nodemon can monitor. Avoid shell operators that detach; instead use a direct executable:

  nodemon --exec "node ./src/index.js"

  If you need to run a script, make sure the script ends with exec node … or similar so the PID is preserved.
• When symlinks are used, watch the real path: nodemon --watch /real/path/to/src or disable symlink resolution with --no-symlink-resolution if supported.
• After applying a change, restart nodemon and verify that a file edit triggers a restart.

Verification

1. Run nodemon with verbose flag: nodemon --verbose.
2. Edit a watched file and save.
3. Check the console for a line similar to [nodemon] restarting due to changes....
4. Confirm the process ID changed: either log process.pid inside the application or run ps -p <old‑pid> -o pid= before and after the edit.
5. If polling is enabled, measure the delay between edit and restart; it should approximate the --pollingInterval value.

Escalation criteria

If after completing the checks and applying the relevant fixes nodemon still does not restart:

• Enable full debugging: nodemon --verbose --inspect and capture the output. Look for any lines indicating that a file‑change event was received or not.
• If the logs show no file‑change events despite the OS delivering them (verified via inotifywait or similar), collect the following details and consider filing an issue on the nodemon GitHub repository:
  • Operating system and version
  • nodemon version (nodemon --version)
  • Watch configuration (nodemon.json or command line)
  • Filesystem layout (e.g., Docker volume mount, WSL version)
  • A minimal reproduction case (a small project that exhibits the problem)
• As a temporary workaround, use an alternative watcher such as watchman or pm2 to restart the process when files change.