Node.js crashes with throw er; // Unhandled 'error' event
throw er; // Unhandled 'error' eventShort 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.
Fix it fast
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:"2Match what you see, then jump to its fix
- 1
code: 'EADDRINUSE' and Emitted 'error' event on Server instancecode is EADDRINUSE: the port is already in useFix - 2
code: '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
code: 'ECONNREFUSED' and the address of a database, cache or APIcode is ECONNREFUSED: a client stream cannot reach its serverFix - 4
The 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
- 1
What does the error look like?
throw er; // Unhandled 'error' eventEmitted '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 :30002Fix
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.js3Verify
The server starts and logs that it is listening.
curl -I http://localhost:3001/Confirmed by nodejs.org
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.js3Verify
The command that failed now runs without the Emitted 'error' line.
npm run buildConfirmed by nodejs.org
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 32Fix
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-server3Verify
The client connects and the process stays up.
node server.jsConfirmed by nodejs.org
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/ | head2Fix
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.jsConfirmed by nodejs.org
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
Back end
Node.js cannot start because the port is already taken
Error: listen EADDRINUSE: address already in use 127.0.0.1:8080
EADDRINUSE means another socket already listens on that port, so Node's listen() was refused.
4 causes, each with a fixBack end
Angular app shows 'Cannot GET /' when served by a Node.js server
Cannot GET /dashboard
Cannot GET / is Express saying no route or file matches the request.
3 causes, each with a fixBack end
Axios call from a React app comes back 404
404 (Not Found)
Status code 404 means a server answered, but it has nothing at that path.
3 causes, each with a fixBack end
bcrypt.hash throws 'data and salt arguments required'
Error: data and hash arguments required
The bcrypt package throws this when hash gets null or undefined for the password or for the salt.
4 causes, each with a fixBack end
bcryptjs rejects hash() or compare() with Illegal arguments
Error: Illegal arguments: string, undefined
bcryptjs checks the types of its two arguments and, when either is wrong, throws Illegal arguments followed by the typeof of the first and the second.
3 causes, each with a fixBack end
Express warns 'body-parser deprecated undefined extended'
body-parser deprecated undefined extended
The warning appears because urlencoded() was called without the extended option, which body-parser 1.x has warned about since version 1.4.0.
3 causes, each with a fix