Maaz Zindani

Loading the index…

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

Node.js crashes with throw er; // Unhandled 'error' event

Errorthrow er; // Unhandled 'error' event

Short answer

Node prints this when an event emitter, such as a server, stream or child process, emits 'error' and nothing listens for it. The crash text is only the wrapper. The line that starts with Emitted 'error' event holds the real error code, such as EADDRINUSE, ENOENT or ECONNREFUSED.

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

Fix it fast

  1. 1Find out which cause you have

    Ignore the first lines and find the one that says Emitted 'error' event on, and the code: field below the stack. That code decides which cause applies.

    node server.js 2>&1 | grep -E "Emitted 'error'|code:|syscall:|path:"
  2. 2Match what you see, then jump to its fix

    1. 1code: 'EADDRINUSE' and Emitted 'error' event on Server instancecode is EADDRINUSE: the port is already in useFix
    2. 2code: 'ENOENT' with a path: or syscall: 'spawn ...' line, often from a build tool or a child processcode is ENOENT: a file or program the code needs does not existFix
    3. 3code: 'ECONNREFUSED' and the address of a database, cache or APIcode is ECONNREFUSED: a client stream cannot reach its serverFix
    4. 4The trace names your own class, a stream or a child process, not a server, and the code is something customYour own emitter or stream has no 'error' listenerFix

What does the error look like?

  • throw er; // Unhandled 'error' event
  • Emitted 'error' event on Server instance at:
  • Error: listen EADDRINUSE: address already in use :::3000

Cause 1 of 4

code is EADDRINUSE: the port is already in use

1Check

Another process already owns the port your server asked for. Often it is your own earlier run that was not stopped.

sudo ss -ltnp | grep :3000

2Fix

Stop the process that owns the port, or start this server on a free port. The full walk-through for finding the owner is on the related page.

kill <pid>
# or choose another port
PORT=3001 node server.js

3Verify

The server starts and logs that it is listening.

curl -I http://localhost:3001/

Confirmed by nodejs.org

Did this fix it?

Cause 2 of 4

code is ENOENT: a file or program the code needs does not exist

1Check

ENOENT is raised when a component of a path does not exist. With spawn, the program being started is the missing path.

ls -l <path from the error>
which <command from syscall spawn>

2Fix

Create or correct the path, or install the program, then run again. For a command inside a project, install the dependencies first.

npm ci
node server.js

3Verify

The command that failed now runs without the Emitted 'error' line.

npm run build

Confirmed by nodejs.org

Did this fix it?

Cause 3 of 4

code is ECONNREFUSED: a client stream cannot reach its server

1Check

ECONNREFUSED means the target machine refused the connection, usually because the service is not running at that address and port.

sudo ss -ltn | grep 6379
curl -v telnet://127.0.0.1:6379 --max-time 3

2Fix

Start the service, or correct the host and port in the config the client reads. Redis and MongoDB each have their own page for this.

sudo systemctl start redis-server

3Verify

The client connects and the process stays up.

node server.js

Confirmed by nodejs.org

Did this fix it?

Cause 4 of 4

Your own emitter or stream has no 'error' listener

1Check

An emitter that fires 'error' with no listener throws the error, prints a stack trace and ends the process. That is by design.

grep -rn "\.on('error'" --include=*.js src/ | head

2Fix

Attach an error listener to every emitter and stream you create, and decide there what to do: log, retry or exit.

const stream = fs.createReadStream('./data.csv');
stream.on('error', (err) => {
  console.error('read failed:', err.code);
});

3Verify

Point the stream at a missing file; the message is logged and the process stays up.

node read.js

Confirmed by nodejs.org

Did this fix it?

How do I stop it coming back?

  • Attach .on('error') to every server, stream, socket and child process when you create it.
  • Read the code: field first; the generic crash text says nothing on its own.
  • Stop dev servers cleanly (Ctrl+C) so a port is not left held by a background process.
  • Log the error code in one central place so alerts say ENOENT or ECONNREFUSED, not Unhandled.

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

Next step

Want this handled for good?

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