Fix Error: listen EADDRINUSE: address already in use :::3000 in Node.js

This error occurs when another process is already listening on the port your Node.js server is trying to bind to. Fix it by finding and stopping the conflicting process, choosing a different port, or ensuring your server shuts down gracefully so the port is released on restart.

Reading the Stack Trace

Here's what each line means:

• at Server.setupListenHandle [as _listen2] (node:net:1872:16): Node's internal net module failed to bind the server socket because the OS reported the address is already taken.
• at Function.listen (node_modules/express/lib/application.js:635:24): Express's app.listen() call delegates to the Node.js net.Server.listen method which encountered the conflict.
• at Object.<anonymous> (src/server.js:28:5): Line 28 of server.js is where your application calls app.listen(3000) to start the HTTP server.

Common Causes

const app = require('./app');
app.listen(3000, () => {
  console.log('Server running on port 3000');
});
// No graceful shutdown handling, Ctrl+C leaves orphaned process

const PORT = 3000;
app.listen(PORT);

// Both api-gateway and user-service configured to use port 3000
app.listen(3000);

The Fix

Read the port from an environment variable with a fallback default. Handle the 'error' event on the server to catch EADDRINUSE and log a clear message. Add SIGTERM handling so the port is released on shutdown.

const app = require('./app');

app.listen(3000, () => {
  console.log('Server running on port 3000');
});

const app = require('./app');

const PORT = parseInt(process.env.PORT, 10) || 3000;

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

server.on('error', (err) => {
  if (err.code === 'EADDRINUSE') {
    console.error(`Port ${PORT} is already in use. Kill the other process or set a different PORT.`);
    process.exit(1);
  }
  throw err;
});

process.on('SIGTERM', () => {
  server.close(() => {
    console.log('Server shut down gracefully');
    process.exit(0);
  });
});

Testing the Fix

const http = require('http');

describe('Server port binding', () => {
  let blockingServer;

  afterEach((done) => {
    if (blockingServer) blockingServer.close(done);
    else done();
  });

  it('starts on the configured PORT', (done) => {
    process.env.PORT = '4999';
    const app = require('./app');
    const server = app.listen(4999, () => {
      expect(server.address().port).toBe(4999);
      server.close(done);
    });
  });

  it('emits error when port is already in use', (done) => {
    blockingServer = http.createServer();
    blockingServer.listen(4998, () => {
      const server2 = http.createServer();
      server2.on('error', (err) => {
        expect(err.code).toBe('EADDRINUSE');
        done();
      });
      server2.listen(4998);
    });
  });
});

Run your tests:

npm test

Pushing Through CI/CD

git checkout -b fix/nodejs-eaddrinuse-graceful-shutdown,git add src/server.js src/__tests__/server.test.js,git commit -m "fix: handle EADDRINUSE and add graceful shutdown",git push origin fix/nodejs-eaddrinuse-graceful-shutdown

Your CI config should look something like this:

name: CI
on:
  pull_request:
    branches: [main]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      - run: npm ci
      - run: npm test -- --coverage
      - run: npx eslint src/

The Full Manual Process: 18 Steps

Here's every step you just went through to fix this one bug:

1. Notice the error alert or see it in your monitoring tool
2. Open the error dashboard and read the stack trace
3. Identify the file and line number from the stack trace
4. Open your IDE and navigate to the file
5. Read the surrounding code to understand context
6. Reproduce the error locally
7. Identify the root cause
8. Write the fix
9. Run the test suite locally
10. Fix any failing tests
11. Write new tests covering the edge case
12. Run the full test suite again
13. Create a new git branch
14. Commit and push your changes
15. Open a pull request
16. Wait for code review
17. Merge and deploy to production
18. Monitor production to confirm the error is resolved

Total time: 30-60 minutes. For one bug.

npm install bugstack-sdk

const { initBugStack } = require('bugstack-sdk')

initBugStack({ apiKey: process.env.BUGSTACK_API_KEY })

Deploying the Fix (Manual Path)

1. Identify and kill the process occupying the port with lsof -i :3000 or netstat.
2. Update server code with graceful shutdown handling.
3. Run tests locally to verify the fix.
4. Open a pull request and wait for CI.
5. Merge and deploy to staging to confirm the port binding works.

Frequently Asked Questions