How to Resolve “EADDRINUSE” in Node.js Server Setup (Step-by-Step Guide)

When setting up a Node.js server, one of the common errors developers encounter is the dreaded EADDRINUSE error. At first glance, this might look cryptic, but it simply means that the port your application is trying to use is already in use by another process.

If you’ve ever run node server.js and been met with this error, you’re not alone. In this guide, we’ll break down what EADDRINUSE means, why it occurs, and step-by-step methods to fix it, along with best practices to prevent it in the future.

1. Understanding the EADDRINUSE Error

The term EADDRINUSE stands for:

• E: Error
• ADDR: Address (IP + port combination)
• INUSE: Already in use

This is Node.js’ way of saying:

“You’re trying to bind the server to a port that’s already taken.”

For example, if your application tries to listen on port 3000 and another application is already using it, Node.js will throw:

Error: listen EADDRINUSE: address already in use :::3000

2. Common Causes of EADDRINUSE

Understanding the root causes can save you time:

1. Another application is already running on the same port
   This could be another Node.js server, Apache, Nginx, or even a completely different service.
2. A previously run Node.js process hasn’t closed properly
   Sometimes after you stop a server with CTRL + C, the process remains in the background.
3. Multiple instances of your application are running
   You may have accidentally launched the server twice.
4. OS port retention
   Some operating systems keep a port reserved for a short time after a process exits.

3. How to Check Which Process Is Using the Port

Before fixing the error, you need to find which process is occupying your desired port.

Windows

Open Command Prompt and run:

netstat -ano | findstr :3000

• The last column is the PID (Process ID).
• To see which application it is:

tasklist /FI "PID eq <PID>"

macOS / Linux

Use:

lsof -i :3000

or:

sudo netstat -lpn | grep :3000

• This will show the process name and PID.

4. Solutions to Fix EADDRINUSE

A. Change the Port Number

The simplest solution is to run your app on a different port:

const PORT = process.env.PORT || 4000;
app.listen(PORT, () => {
    console.log(`Server running on port ${PORT}`);
});

Then:

node server.js

Now your server runs on 4000 instead of 3000.

B. Kill the Process Using the Port

If you want to keep the same port, you can terminate the conflicting process.

Windows:

taskkill /PID <PID> /F

macOS / Linux:

kill -9 <PID>

C. Automatically Find a Free Port

You can make your Node.js app find an available port automatically:

const net = require('net');

function findAvailablePort(startPort) {
  return new Promise((resolve, reject) => {
    const server = net.createServer();
    server.listen(startPort, () => {
      server.once('close', () => resolve(startPort));
      server.close();
    });
    server.on('error', () => {
      resolve(findAvailablePort(startPort + 1));
    });
  });
}

findAvailablePort(3000).then((port) => {
  app.listen(port, () => {
    console.log(`Server running on port ${port}`);
  });
});

D. Use process.on('uncaughtException') for Graceful Handling

You can catch the error and respond accordingly:

process.on('uncaughtException', (err) => {
  if (err.code === 'EADDRINUSE') {
    console.error('Port is in use. Please try another one.');
    process.exit(1);
  }
});

E. Restart the Development Environment

Sometimes, simply restarting your terminal, stopping all Node processes, or rebooting your machine clears the issue:

killall node

(macOS / Linux)
or use Task Manager on Windows to end all Node.js processes.

5. Best Practices to Prevent EADDRINUSE

• Use environment variables for ports
  Example .env file: PORT=3000 And in your code: const PORT = process.env.PORT || 3000;
• Always close servers properly
  When shutting down your app: process.on('SIGTERM', () => { server.close(() => { console.log('Server closed gracefully'); }); });
• Avoid hardcoding ports in multiple files
  Store them in a config file or environment variable to prevent mismatches.
• Use tools like nodemon for development
  This helps avoid multiple manual server starts.

6. When the Error Is Not About the Port

Occasionally, you might get an EADDRINUSE even when you think the port is free. This can happen if:

• Your app tries to bind to the same port twice in the code.
• There’s a socket reuse issue.
• Firewall or network settings are interfering.

In such cases, double-check your code and system settings.

Conclusion

The EADDRINUSE error in Node.js is not a bug in your code — it’s a networking conflict where two processes want the same port. By knowing how to identify the process using the port, how to free it, and how to prevent the issue, you can get back to coding quickly without frustration.

Keep your ports organized, use environment variables, and always handle shutdowns gracefully to avoid this error in the future.