Diagnosing Nodemon Restart Failures and Thrash with Custom Watch Patterns

When Nodemon Misses Changes or Restarts Endlessly

You save a file in your Node.js project. Nodemon does nothing—no restart log, no console output. Or worse, a single save triggers three restarts in two seconds, each one reloading your database connections and clearing in-memory state. Both symptoms point to a mismatch between what you think nodemon is watching and what it actually watches. The fix is not "add more flags" but "verify the effective watch set" and then adjust --watch and --ignore until the observed behavior matches the intended scope.

Recognizable Conditions

Symptom	What You See in the Terminal
Missed restart	File saved, no [nodemon] restarting due to changes... line, process keeps running old code
Thrash / repeated restarts	Multiple restarting due to changes lines within seconds of one save; often triggered by node_modules, dist/, or editor temp files (.swp, ~)
Inconsistent across files	Edits to src/index.ts restart reliably; edits to src/utils/helpers.ts do not

Cause-to-Symptom Mapping

Observed Behavior	Most Likely Cause	Why It Happens
No restart for a changed file	File outside effective watch root	Default watch root is the directory containing the entry script; custom --watch globs may not cover the file's directory
No restart for a changed file	File matched by an --ignore pattern	Ignore patterns are evaluated before watch patterns; a broad --ignore "**/*.map" can suppress TypeScript source maps that sit next to .ts files
No restart for a changed file	Watch glob does not match the path	--watch src watches src/**/* but not src/**/.* (dotfiles) or symlinked directories outside the tree
Multiple rapid restarts	Editor atomic save creates temp files	VS Code, WebStorm, and Vim often write to .tmp or ~ then rename; each filesystem event can trigger a restart if not ignored
Multiple rapid restarts	Ignored directories not excluded from watch	node_modules or dist inside a watched tree generate events on install/build; without explicit --ignore they fire restarts
Multiple rapid restarts	--watch set too broad	--watch . at repo root catches .git, coverage, .cache and editor metadata

Ordered Diagnostic Checks

1. Print the effective watch configuration. Run nodemon --list from the project root (same directory where you invoke nodemon). This shows every resolved watch directory and ignore pattern after glob expansion. No special permissions needed; read access to the project is sufficient.
2. Confirm the changed file path is inside a watched directory and not ignored. Compare the absolute path of the file you edited against the Watching: lines from --list. Then check each Ignoring: pattern—does the file match any? Remember: ignore wins.
3. Trigger a controlled filesystem event. In a second terminal, run touch path/to/your/file.ts (or echo "// test" >> path/to/your/file.ts on Windows PowerShell). Watch the nodemon log timestamps. A single restart within 1–2 seconds is expected; zero or >2 restarts indicates a pattern problem.
4. Isolate the entry point. Verify the --exec command (or script in nodemon.json) points to the actual runtime entry file. A mismatch here looks like a missed restart because the process restarts but runs stale code.

Fixes Tied to Findings

File Outside Watch Root

Add an explicit --watch glob that covers the directory. For a monorepo with packages under packages/*/src:

nodemon --watch packages/*/src --exec "ts-node" packages/api/src/index.ts

Run nodemon --list again to confirm the new paths appear under Watching:.

File Suppressed by Ignore Pattern

Narrow the ignore pattern. If --ignore "**/*.map" blocks src/**/*.map but you only want to ignore build output, change to:

--ignore "dist/**/*.map" --ignore "build/**/*.map"

Test by touching a source map in src/ and confirming a restart occurs.

Editor Atomic Save Thrash

Add a coalescing delay and ignore editor temp patterns:

nodemon --delay 300ms --ignore "**/*.swp" --ignore "**/*~" --ignore "**/.#*" --exec "node" dist/index.js

--delay waits for quiet time before restarting; 150–500 ms covers most editors. Adjust up if thrash persists.

Build Artifacts and Dependency Trees Triggering Restarts

Explicitly ignore output directories at the root of the watch tree:

--ignore "node_modules" --ignore "dist" --ignore "build" --ignore "coverage" --ignore ".cache" --ignore ".turbo"

Place these after your --watch flags; order does not affect precedence (ignore always wins), but readability improves.

Complete Example for a TypeScript Monorepo

nodemon \
  --watch packages/api/src \
  --watch packages/shared/src \
  --ignore "**/*.map" \
  --ignore "**/*.d.ts" \
  --ignore "node_modules" \
  --ignore "dist" \
  --ignore "coverage" \
  --ignore "**/*.swp" \
  --ignore "**/*~" \
  --delay 250ms \
  --exec "ts-node --transpile-only" packages/api/src/main.ts

Run nodemon --list once after composing the command to verify the final resolved patterns.

Escalation Criteria

Escalate beyond pattern tuning when:

• Restarts remain inconsistent across files after patterns are corrected and verified with --list.
• Nodemon logs EMFILE, ENOSPC, or watcher limit warnings—indicating OS file-descriptor or inotify limits.
• Behavior differs materially between Linux, macOS, and Windows (e.g., works on macOS but misses events on Windows), suggesting native watcher (fs.watch) limitations. Consider --legacy-watch (polling) or a dedicated file-watcher service like chokidar via a custom script.

Limitations and Verification

Watch behavior is version-sensitive. Nodemon 3.x defaults to chokidar on all platforms; 2.x used native fs.watch on Linux/macOS and polling on Windows. The --legacy-watch flag forces polling, which is slower but more reliable on network mounts or containers with broken inotify.

Practical verification step: After any pattern change, run the controlled touch test (step 3 above) on three representative files: one in the primary source tree, one in a newly added watch directory, and one that should be ignored (e.g., a file in dist/). Confirm exactly one restart for the first two and zero for the third. If results match, the configuration is sound.