Como corrigir erro de porta EADDRINUSE já em uso no Node.js

O erroErro: escute EADDRINUSE: endereço já em uso :::3000 significa que outro processo já está usando a porta que seu aplicativo Node.js deseja. É um dos erros mais comuns durante o desenvolvimento. Aqui estão todas as maneiras de consertar isso.

O que causa esse erro

• Uma instância anterior do servidor não foi encerrada corretamente e ainda mantém a porta
• Outro aplicativo está usando a mesma porta (outro servidor de desenvolvimento, banco de dados)
• Um processo travado deixou um zumbi segurando a porta
• Você iniciou seu servidor duas vezes

Correção 1: Encontre e elimine o processo (macOS/Linux)

# Find the process using port 3000
lsof -i :3000
# COMMAND   PID  USER   FD   TYPE  DEVICE  NODE NAME
# node    12345  you   20u  IPv6  ...     TCP  *:3000 (LISTEN)

# Kill it by PID
kill -9 12345

# Or do it in one command
kill -9 $(lsof -ti :3000)

# Kill all node processes (nuclear option)
killall -9 node

Correção 2: Encontre e elimine o processo (Windows)

# Find the process using port 3000
netstat -ano | findstr :3000
# TCP    0.0.0.0:3000    0.0.0.0:0    LISTENING    12345

# Kill it by PID
taskkill /PID 12345 /F

# PowerShell one-liner
Stop-Process -Id (Get-NetTCPConnection -LocalPort 3000).OwningProcess -Force

Correção 3: use uma porta diferente

// Make the port configurable via environment variable
const PORT = process.env.PORT || 3000;

app.listen(PORT, () => {
  console.log("Server running on port " + PORT);
});

// Then run with a different port:
// PORT=3001 node server.js

Correção 4: lidar com o erro com elegância

const server = app.listen(PORT);

server.on('error', (err) => {
  if (err.code === 'EADDRINUSE') {
    console.error("Port " + PORT + " busy. Trying " + (PORT + 1));
    server.listen(PORT + 1);  // fall back to next port
  } else {
    throw err;
  }
});

Correção 5: Implemente o desligamento normal (evita o problema)

A causa raiz geralmente é um servidor que não libera a porta na saída. Adicione manipuladores de desligamento elegante:

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

function shutdown(signal) {
  console.log(signal + " received. Closing server...");
  server.close(() => {
    console.log("Server closed. Port released.");
    process.exit(0);
  });
  setTimeout(() => {
    console.error("Forced shutdown");
    process.exit(1);
  }, 10000);
}

process.on('SIGTERM', () => shutdown('SIGTERM'));
process.on('SIGINT', () => shutdown('SIGINT'));  // Ctrl+C

Correção 6: use nodemon para reinicializações limpas

npm install --save-dev nodemon

# package.json
{
  "scripts": {
    "dev": "nodemon server.js"
  }
}

# nodemon cleanly restarts and releases ports between reloads
npm run dev

Script Kill-Port reutilizável

# kill-port.sh
#!/bin/bash
PORT=${1:-3000}
PID=$(lsof -ti :$PORT)
if [ -n "$PID" ]; then
  echo "Killing process $PID on port $PORT"
  kill -9 $PID
else
  echo "No process on port $PORT"
fi

# Usage: ./kill-port.sh 3000

Perguntas Frequentes

P: Por que a porta permanece em uso depois que paro meu aplicativo?
R: Geralmente porque o processo foi encerrado abruptamente sem liberar o soquete ou porque um processo filho ainda o mantém. Os manipuladores de desligamento gracioso evitam isso.

P: O que significa ::: em ‘:::3000’?
R: Notação IPv6 para “todas as interfaces” (como 0.0.0.0 em IPv4). Seu servidor se liga a todas as interfaces de rede na porta 3000.

P: Dois aplicativos podem compartilhar a mesma porta?
R: Não — apenas um processo pode se vincular a uma porta em uma interface por vez. Use portas diferentes ou um proxy reverso (nginx) para rotear por caminho/domínio.

P: Como evito isso no Docker?
R: Cada contêiner possui seu próprio namespace de rede, portanto, os conflitos só acontecem no mapeamento do host. Mapeie diferentes portas de host:-p 3001:3000.

P: O nó killall é seguro?
R: Ele mata TODOS os processos do Node.js – bom no desenvolvimento, mas cuidado se você tiver outros aplicativos do Node que não deseja que sejam interrompidos.

Conclusão

EADDRINUSE significa que a porta já está ocupada. Correção rápida:encontre o processo comlsof -ti :PORT e matá-lo. Correção permanente:adicionar manipuladores de desligamento elegantes então seu servidor sempre libera a porta na saída e usenodemon em desenvolvimento para reinicializações limpas. Tornando a porta configurável viaprocess.env.PORT também evita conflitos instantaneamente.