Diagnosing nodemon Restart Failures After File Changes

Recognizable condition

You edit a source file, save it, but nodemon does not log a restart message and the Node process continues running with the old code.

Cause / diagnostic table

Symptom	Likely cause
No restart, console silent	File ignored by nodemon ignore patterns
Restart works after a delay	File‑system events not propagated (polling vs watch)
Error about access when starting	Permission issue preventing nodemon from reading files
Only compiled output changes trigger restart	Source maps or generated files not watched
Problem appears inside Docker or WSL	Limited file‑change notifications in those environments

Ordered checks

1. Verify nodemon invocation – run nodemon --version and ensure you are launching the app with nodemon your‑script.js (or via npm script).
2. Look for ignore warnings – start nodemon with --debug-* or NODEMON_DEBUG=* and watch the console for lines like Ignored: path/to/file.js.
3. Test basic startup – run nodemon --inspect-brk your‑script.js to confirm the process starts and pauses.
4. Disable ignore rules temporarily – launch with nodemon --ignore '' your‑script.js. If a restart now occurs, an ignore pattern was the cause.
5. Switch watch mode – try nodemon --legacy-watch your‑script.js or set a poll interval --poll 1000. A restart after this indicates the default watcher missed events.
6. Check file permissions – ensure the user running nodemon can read the watched files (ls -l and whoami).
7. Isolate environment – run the same command outside Docker/WSL (e.g., directly on the host) to see if the issue persists.

Fixes tied to findings

• Adjust ignore patterns – edit nodemon.json or CLI to exclude only necessary directories, e.g.:

{
  "ignore": ["node_modules/", "build/", "*.test.js"]
}

• Enable legacy watcher – add "legacyWatch": true to nodemon.json or use --legacy-watch.
• Use polling – set "pollInterval": 1000 (milliseconds) in config or --poll 1000.
• Correct permissions – change ownership or mode: sudo chown -R $USER:$USER /path/to/project or chmod +r on specific files.
• Docker/WSL adjustments – when using Docker, mount source with a bind volume and enable polling: nodemon --poll 2000 your‑script.js. In WSL, ensure the project resides on the Linux filesystem or use --exec" "npm start" with Windows‑side editing.

Escalation criteria

If the above checks do not produce a restart:

1. Collect full debug output: NODEMON_DEBUG=* nodemon your‑script.js 2>debug.log and examine the log for watcher or restart events.
2. Check OS file‑watch limits: on Linux run cat /proc/sys/fs/inotify/max_user_watches. If the value is low, increase it temporarily (echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p) and test again.
3. Consider alternative tools for development, such as Node’s built‑in --watch flag (Node ≥18) or a process manager like pm2.
4. If the problem persists, file an issue on the nodemon GitHub repository, attaching the debug log, nodemon version, OS details, and container/WSL information.

Verification

After applying a fix, edit a watched source file (e.g., add console.log('changed')) and save. nodemon should log a restart message and the new output should appear in the terminal. The debug output should contain a line similar to watch: /path/to/file.js followed by restarting. If the restart does not occur, revisit the checks above.