Diagnosing Nodemon Restart Failures and Watcher Issues

The Problem: Silent Failures and Missed Restarts

A common frustration when using nodemon is the "silent failure": you save a file in your editor, but the application does not restart, and the console remains static. In other cases, nodemon may enter a restart loop or crash with a Cannot find module error immediately after a change.

The core issue is usually a mismatch between the file system events and nodemon's configuration. If the watcher is looking at the wrong directory or is overwhelmed by too many files, it will fail to trigger the exec command required to reboot your process.

Diagnostic Matrix

Use this table to match your symptoms to the most likely cause before proceeding to the ordered checks.

Symptom	Likely Cause	Diagnostic Indicator
No console output after saving a file	Incorrect watch path	File is outside the configured watch directory
Infinite restart loop	Circular watch/ignore	App writes to a file that nodemon is watching
High CPU usage / Laggy restarts	Over-broad watch patterns	Watching node_modules or large build folders
Restart occurs, but code is old	Transpilation mismatch	Watching .ts files but executing .js without a build step

Step-by-Step Troubleshooting

1. Validate Watch and Ignore Paths

Nodemon relies on a list of directories to monitor. If your source code is in /src but nodemon is watching the root, it may miss events depending on the OS. Conversely, watching everything can exhaust system resources.

Check your nodemon.json or the nodemonConfig section of your package.json. Ensure your configuration follows this pattern:

{
  "watch": ["src", "config"],
  "ignore": ["node_modules/**", "dist/**", "*.log", ".tmp/**"]
}

Risk: Avoid using "watch": ["*"]. On large projects, this can lead to the OS hitting the maximum number of file watchers (inotify limits on Linux), causing nodemon to stop responding entirely.

2. Verify Execution Logic for Transpilers

If you are using TypeScript or Babel, nodemon must be told exactly what to execute. A common mistake is watching the source files but executing the source files directly without a compiler, or executing the build folder while watching the source without a trigger to rebuild.

If you use a build step, configure the execMap to handle specific extensions:

{
  "execMap": {
    "ts": "ts-node"
  }
}

Run this command in your terminal to verify which files nodemon is actually tracking:

# Run with the --verbose flag to see event triggers
nodemon --verbose index.js

3. Check for Resource Exhaustion (Linux/macOS)

If the configuration is correct but restarts still fail, your operating system may have reached its file descriptor limit. This is common in monorepos.

Run the following command to check your current ulimit (maximum open files):

# Run in the system shell
ulimit -n

If the number is low (e.g., 1024), you may need to increase it via sysctl or by adding fs.inotify.max_user_watches=524288 to /etc/sysctl.conf.

Applying the Fix

Based on your findings, apply the corresponding fix:

• For missed events: Explicitly add the source directory to the watch array in nodemon.json.
• For restart loops: Add the directory where your app writes logs or temporary files to the ignore array.
• For resource lag: Narrow the watch scope from the root directory to specific folders (e.g., src/).

Verification and Rollback

To verify the fix, perform these three checks:

1. Modify a file inside a watch directory. You should see [nodemon] restarting due to changes... in the console.
2. Verify the application logic has updated (e.g., check a changed API response).
3. Modify a file inside an ignore directory (like dist/). Nodemon should not restart.

Rollback: If the new configuration causes the application to fail to start, delete the nodemon.json file or revert the package.json changes to return to default behavior.

Escalation Criteria

If the above steps do not resolve the issue, escalate the problem by collecting the following data for a bug report or senior engineer:

• The output of nodemon --version and node -v.
• The full content of the nodemon.json file.
• The OS version and the result of ulimit -n.
• Whether the issue persists when running with nodemon -L (legacy watch mode, which uses polling instead of native OS events).