~ / hub / erros / EADDRINUSE: porta já está em uso
4 out 2026errosguia de solução

EADDRINUSE: porta já está em uso

Outro processo já ocupa a porta. Ache-o e decida: encerrar ou trocar.

1. Significado

Error: listen EADDRINUSE: address already in use :::3000 quer dizer que sua aplicação tentou escutar em uma porta que outro processo já está usando (ou que o sistema ainda não liberou). A mesma ideia aparece como “Address already in use” em Python, Go, Java e servidores web.

2. Descubra quem usa a porta

# Linux / macOS
sudo ss -ltnp 'sport = :3000'
sudo lsof -i :3000

# Windows (PowerShell / CMD)
netstat -ano | findstr :3000
tasklist /FI "PID eq 12345"

A saída traz o nome do programa e o PID. Veja mais em ss e lsof.

3. Decida o que fazer

  • É uma instância antiga da sua própria app (terminal esquecido, processo em segundo plano): encerre com kill PID (Windows: taskkill /PID 12345 /F).
  • É outro serviço legítimo (outro projeto, um proxy): mude a porta da sua aplicação, por exemplo via variável PORT=3001.
  • É um contêiner Docker: veja docker ps e pare o contêiner, ou altere o mapeamento -p 3001:3000.

4. Evite o problema

  • Leia a porta de uma variável de ambiente, com valor padrão, em vez de fixá-la no código.
  • Em modo de desenvolvimento com recarga automática, use ferramentas que encerram o processo anterior (nodemon, ts-node-dev, air) e trate o sinal SIGTERM para fechar o servidor.
  • Se a porta aparece em TIME_WAIT logo depois de reiniciar, aguarde alguns segundos; servidores bem escritos usam a opção de reutilização de endereço (SO_REUSEADDR).

5. Portas abaixo de 1024

Escutar em portas como 80 e 443 exige privilégios no Linux. Se o erro for EACCES em vez de EADDRINUSE, o problema é permissão: use um proxy reverso (Nginx, Caddy) na frente da aplicação.

DICA Antes de “matar” um PID, confira o nome do processo. Encerrar o banco de dados sem querer é pior que trocar a porta.

Continue explorando

← erros · ss · lsof · ECONNREFUSED · docker

Veja também o hub de conteúdo, o glossário e os cursos gratuitos.

Quer aplicar no seu time?

Diagnóstico gratuito de 30 minutos.

solicitar →