ECONNREFUSED — conexão recusada (guia completo)

1. Significado

ECONNREFUSED quer dizer: o cliente conseguiu resolver o host e tentar o TCP, mas nada aceitou a conexão naquela porta (ou um firewall respondeu como “recusado”).

2. Diferencie de outros erros

• ECONNREFUSED — porta fechada / processo down
• ETIMEDOUT — pacote engolido (firewall, rota, security group)
• ENOTFOUND — DNS não resolveu o hostname
• ECONNRESET — conexão aberta e derrubada no meio

3. Checklist de diagnóstico

# 1. Algo escuta a porta?
ss -lntp | grep 3000
# Windows: netstat -ano | findstr 3000

# 2. Health local
curl -v http://127.0.0.1:3000/health

# 3. Docker: porta publicada?
docker ps --format "table {{.Names}}\t{{.Ports}}"

# 4. Logs do serviço
docker logs --tail 100 api
journalctl -u minha-api -n 50 --no-pager

4. Armadilha clássica no Docker Compose

# ERRADO de dentro de outro container:
DATABASE_URL=postgres://user:pass@localhost:5432/db

# CERTO — use o nome do serviço na rede Compose:
DATABASE_URL=postgres://user:pass@db:5432/db

localhost dentro do container é o próprio container, não o host nem o serviço irmão.

5. Causas frequentes

• App crashou na subida (exception não tratada)
• .env com porta antiga ou host errado
• Security group / ufw bloqueando (pode parecer timeout)
• Bind apenas em 127.0.0.1 quando o client está em outra máquina

← erros · curl · Compose produção