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 pse 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
SIGTERMpara fechar o servidor. - Se a porta aparece em
TIME_WAITlogo 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.