Resolving "throw er; // Unhandled 'error' event" in ExpressJS: Analysis and Solutions for Port Occupancy Issues

Problem Description and Error Analysis

When developing an ExpressJS application, after creating it with commands like express -e folderName, npm install ejs --save, and npm install, running node app.js may result in the following error:

events.js:72
    throw er; // Unhandled 'error' event
          ^
Error: listen EADDRINUSE
    at errnoException (net.js:884:11)
    at Server._listen2 (net.js:1022:14)
    at listen (net.js:1044:10)
    at Server.listen (net.js:1110:5)
    at Object.<anonymous> (folderName/app.js:33:24)
    at Module._compile (module.js:456:26)
    at Object.Module._extensions..js (module.js:474:10)
    at Module.load (module.js:356:32)
    at Function.Module._load (module.js:312:12)
    at Function.Module.runMain (module.js:497:10)

The core of this error is EADDRINUSE, indicating that the port the application is trying to listen on is already occupied by another process. In Node.js, when a server fails to bind to a specified port, it triggers an unhandled error event, causing the process to throw an exception and terminate.

Port Occupancy Detection Methods

To confirm if a port is occupied, system commands can be used for detection. Here are two common methods:

Using the netstat Command

On Linux or macOS systems, run the following command to check the usage of a specific port (e.g., 8080):

netstat -tulnp | grep 8080

This command lists all processes listening on the specified port along with their PIDs, helping to identify the application occupying the port.

Using the lsof Command

lsof (List Open Files) is another powerful tool that displays open files and network connections. Run:

lsof -i :8080

This outputs detailed information about the process occupying port 8080, including the command name and PID.

Solutions

Based on the detection results, the following measures can be taken to resolve port occupancy issues:

Terminate the Occupying Process

If another Node.js server or application is found using the same port, the simplest method is to kill that process. Use the kill -9 PID command (where PID is the process ID obtained from the above commands) to force-stop the process, then rerun node app.js.

Change the Application Port

If the occupying process cannot be terminated, modify the listening port of the Express application. In the app.js file, locate a line similar to:

app.listen(8080);

Change it to an unused port, such as 3000:

app.listen(3000);

Save the file and restart the application to avoid port conflicts.

Other Related Errors and Handling

Reference articles indicate that the "throw er; // Unhandled 'error' event" error may not only be caused by port occupancy but could also relate to file system watcher limits. For example, when running file watch commands (e.g., npm run watch) on Linux systems, an ENOSPC error might be triggered due to the system's file watcher limit being reached.

Solutions for File Watcher Limits

If the error message includes ENOSPC, it indicates insufficient system file watchers. This can be resolved through the following steps:

1. Delete the node_modules directory: rm -rf node_modules
2. Clear the NPM cache: npm cache clear --force
3. Reinstall dependencies: npm install

Additionally, the file watcher limit can be increased by modifying system configuration. Edit the /etc/sysctl.conf file and add the following line:

fs.inotify.max_user_watches=524288

Then run sudo sysctl -p to apply the changes.

Prevention and Best Practices

To avoid such errors, it is recommended during development to:

• Use dynamic port configuration, e.g., setting the port via environment variables.
• Add error handling logic in the application to catch and log unhandled error events.
• Regularly check and manage running processes to prevent unnecessary port occupancy.

By applying these methods, developers can effectively diagnose and resolve port occupancy and file watcher issues in ExpressJS, ensuring stable application operation.