Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

nodemon says the app crashed and stops restarting

Error[nodemon] app crashed - waiting for file changes before starting...

Short answer

Nodemon prints this when your script exits with a non-zero code. It is not a nodemon fault: the real error is printed just above that line. Read it, then check the three usual causes: an uncaught exception or rejected promise, a missing env file, or a debugger port that is already taken.

  • Applies to nodemon 3, Node.js 22, Node.js 24
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Run nodemon with --verbose and scroll up from the crash line. The stack trace or error message above it is the actual problem. If the last line says 'clean exit' instead, the script ended with code 0 and nothing crashed.

    npx nodemon --verbose server.js
  2. 2Match what you see, then jump to its fix

    1. 1A stack trace is printed right above 'app crashed'An uncaught exception or unhandled promise rejection ended the processFix
    2. 2Node.js exits at once, before your code runs, with an error about the env fileThe --env-file path does not existFix
    3. 3Starting inspector on 127.0.0.1:9229 failed: address already in useThe inspector port is already in use by an older processFix

What does the error look like?

  • [nodemon] app crashed - waiting for file changes before starting...
  • [nodemon] clean exit - waiting for changes before restart

Cause 1 of 3

An uncaught exception or unhandled promise rejection ended the process

1Check

Nodemon logs the crash message when the child process exits with a non-zero code or is killed by a signal it did not send. Node.js exits with code 1 after an uncaught exception, and an unhandled promise rejection is raised as an uncaught exception by default. Run the script without nodemon to see the same trace.

node server.js
echo "exit code: $?"

2Fix

Fix the line named in the trace. For async code, catch the rejection (try/catch around await, or .catch) so one failed database call does not end the process.

async function start() {
  try {
    await connectDb();
    app.listen(3000);
  } catch (err) {
    console.error('startup failed:', err);
    process.exit(1);
  }
}
start();

3Verify

Save the file. Nodemon restarts the app and prints 'starting' with no crash line after it.

npx nodemon server.js

Confirmed by nodejs.org

Did this fix it?

Cause 2 of 3

The --env-file path does not exist

1Check

Node.js throws an error when a file passed to --env-file is missing, and the path is read relative to the folder you started nodemon in. Starting nodemon from a parent folder breaks it.

pwd
ls -la .env

2Fix

Start nodemon from the project folder, pass the right path, or use --env-file-if-exists when the file is optional.

npx nodemon --exec "node --env-file=.env" server.js
# optional file:
npx nodemon --exec "node --env-file-if-exists=.env" server.js

3Verify

The app starts and reads PORT or your other variables.

node --env-file=.env -e "console.log(process.env.PORT)"

Confirmed by nodejs.org

Did this fix it?

Cause 3 of 3

The inspector port is already in use by an older process

1Check

When you run with --inspect, a previous Node.js process may still hold the debugger port. Nodemon's own FAQ lists this case.

lsof -i :9229 -t

2Fix

Stop the old process, or have nodemon free the port on every restart with an events entry in nodemon.json.

{
  "events": {
    "restart": "sh -c 'lsof -i :${PORT:-9229} -t | xargs kill'"
  }
}

3Verify

Edit and save a file twice in a row. Both restarts should start cleanly.

npx nodemon --inspect server.js

Confirmed by github.com

Did this fix it?

How do I stop it coming back?

  • Keep a start script that runs the app with plain node, so the same trace is easy to reproduce without nodemon.
  • Add process-level logging for uncaughtException and unhandledRejection so a crash always leaves a clear message.
  • Start nodemon from the project root, so relative paths such as .env resolve the same way every time.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Back end

ng serve says it cannot determine the project or target

Cannot determine project for command.

The Angular CLI looked through angular.json for a project that defines the target you asked for (serve, build, test) and found none, or found several and could not pick one.

3 causes, each with a fix

Back end

ng serve cannot find the dev-server builder package

Could not find the implementation for builder @angular/build:dev-server

The builder named in angular.json (for example @angular-devkit/build-angular:dev-server) is looked up as an npm package starting from the workspace root.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.