ERR_CONNECTION_REFUSED: como descobrir se o problema é porta, serviço, proxy ou firewall

ERR_CONNECTION_REFUSED significa que o navegador não conseguiu estabelecer conexão com o endereço e a porta de destino. Em geral, nenhum processo está escutando ali ou alguma camada rejeitou ativamente a tentativa. É diferente de timeout, no qual não chega uma resposta conclusiva, e diferente de erro HTTP, que só existe depois que a conexão foi aceita.

Este guia organiza o diagnóstico do cliente até o processo: confirmar URL e porta, testar com curl, verificar quem escuta, analisar 127.0.0.1 versus 0.0.0.0, conferir proxy, contêiner, IPv4/IPv6 e firewall. O objetivo é achar a primeira camada quebrada sem desligar segurança ou reinstalar a rede.

Legenda: a recusa acontece antes do HTTP; cada etapa reduz as possíveis causas.

Recusa, timeout e resposta HTTP

Uma recusa costuma ser imediata. O sistema recebeu um pacote de rejeição ou sabe que não há serviço naquela porta. Um timeout demora porque pacotes foram descartados, rota falhou ou o destino não respondeu. 404, 502 e 503 provam que algum servidor HTTP respondeu.

Teste:

curl -v --connect-timeout 5 http://127.0.0.1:8080/

O modo verboso mostra endereços tentados e etapa da falha. Não use -k para ignorar certificado como resposta padrão; TLS ocorre depois da conexão TCP e merece diagnóstico próprio.

Confirme esquema, host e porta

URLs sem porta usam padrões: HTTP 80 e HTTPS 443. Um servidor de desenvolvimento pode estar em 3000, 5173 ou 8000. Compare a saída da aplicação com a URL aberta.

http://localhost:8000
https://localhost:8000

Essas URLs não são equivalentes. Se o processo oferece HTTP e o navegador tenta HTTPS, a conexão pode ser aceita e falhar no TLS; dependendo da ferramenta, a mensagem muda. Copie a URL exata impressa pelo servidor.

Evite testar produção por IP quando o serviço depende do host virtual e TLS. Para diagnóstico local, comece pelo endereço documentado.

Use um servidor local conhecido

Crie uma pasta vazia e execute:

python -m http.server 8080 --bind 127.0.0.1

Em outro terminal:

curl -I http://127.0.0.1:8080/

Se funciona, a pilha local e a porta estão operacionais. Encerre com Ctrl+C. Se a aplicação real falha na mesma máquina, compare comando, porta e endereço de bind.

Não exponha esse servidor à internet nem o use para arquivos sensíveis. Ele é somente um laboratório local.

Verifique se o processo está vivo

Linux:

ss -ltnp
ss -ltnp | grep ':8080'

macOS:

lsof -nP -iTCP:8080 -sTCP:LISTEN

Windows PowerShell:

Get-NetTCPConnection -State Listen -LocalPort 8080
Get-Process -Id (Get-NetTCPConnection -State Listen -LocalPort 8080).OwningProcess

Execute com permissões normais primeiro. O resultado deve mostrar endereço local, porta e processo. Se não há ouvinte, examine o log de inicialização; firewall não faz um processo aparecer.

127.0.0.1, 0.0.0.0 e endereço da rede

Um serviço ligado a 127.0.0.1 aceita apenas conexões da própria máquina. Isso é apropriado para desenvolvimento. Para receber tráfego de proxy ou contêiner, pode precisar de 0.0.0.0 ou interface específica.

0.0.0.0 é endereço de bind, não destino para o navegador. Acesse 127.0.0.1 localmente ou o IP real da interface a partir de outra máquina autorizada.

Não altere para 0.0.0.0 sem avaliar autenticação e firewall. Expor um painel de desenvolvimento na rede pode revelar dados ou permitir alterações.

Legenda: o bind define quais interfaces aceitam conexões; a URL usa um endereço real.

localhost pode resolver para IPv4 ou IPv6

localhost pode retornar ::1 e 127.0.0.1. Se o serviço escuta apenas IPv4, a primeira tentativa IPv6 pode falhar.

curl -4 -v http://localhost:8080/
curl -6 -v http://localhost:8080/

Compare com 127.0.0.1 e [::1]. Corrija o bind ou a resolução conforme a necessidade; não remova IPv6 do sistema apenas por um serviço mal configurado.

Verifique o arquivo hosts somente se existe evidência de alteração. Entradas duplicadas ou domínio de teste antigo podem direcionar para a máquina errada.

Aplicação inicia e encerra antes do teste

O terminal pode mostrar “listening” e logo depois uma exceção. Confira se o processo continua ativo e leia o log completo. Em gerenciadores de processos, consulte o estado e o número de reinícios.

Uma aplicação pode validar banco ou variável depois de abrir a porta e encerrar ao falhar. A conexão alterna entre funcionar e recusar. Registre horários e correlacione com inicialização.

Não mantenha um processo quebrado em reinício infinito. Corrija a dependência ou configuração e defina limite de tentativas.

Proxy reverso: origem recusando

Se o navegador recebe 502 Bad Gateway, o proxy aceitou sua conexão, mas pode ter recebido “connection refused” ao chamar a origem. Leia o log do proxy e teste a origem a partir do mesmo ambiente de rede:

curl -v http://127.0.0.1:8000/health

Dentro de contêiner, 127.0.0.1 aponta para o próprio contêiner, não para o host ou outro serviço. Use o nome do serviço na rede definida e a porta interna correta.

Evite expor a origem publicamente só para o proxy alcançá-la. Configure rede interna e regras mínimas.

Docker: porta publicada e porta interna

docker ps
docker port nome-do-container
docker logs --tail 100 nome-do-container

Em -p 8080:80, o host recebe em 8080 e encaminha para 80 do contêiner. A aplicação dentro dele precisa escutar na porta 80 e em interface adequada.

docker inspect nome-do-container --format '{{json .NetworkSettings.Ports}}'

Se o contêiner encerrou, a porta deixa de existir. Diagnostique o processo antes de alterar o mapeamento. O guia do IATechNerds sobre contêiner encerrado complementa esse caso quando publicado.

Firewall: teste depois de provar o ouvinte

Se o processo escuta e a conexão local funciona, mas outra máquina autorizada falha, examine firewall do host, rede e nuvem. Não desative tudo. Adicione uma regra temporária, limitada à porta, origem e protocolo necessários, conforme a política do ambiente.

Uma recusa externa pode vir de regra com ação reject; descarte costuma parecer timeout. Compare teste local, teste na mesma rede e teste do cliente real.

Registre a regra anterior e tenha plano de reversão. Painéis administrativos não devem ser expostos apenas para provar conectividade.

VPN, proxy do sistema e extensões

Um proxy configurado no navegador ou sistema pode interceptar a URL. Compare:

curl -v --noproxy '*' http://localhost:8080/

Use isso apenas para um destino local confiável. Em rede corporativa, não contorne controles para acessar serviços externos. Peça validação da equipe responsável.

Extensões raramente explicam uma recusa TCP direta, mas podem trocar URL. Confirme no DevTools qual endereço foi solicitado. Uma janela privada pode ajudar a isolar configuração sem apagar dados.

Serviço remoto e DNS

Confira resolução:

nslookup exemplo.test

ou:

dig +short exemplo.test

Depois compare os endereços mostrados por curl -v. DNS correto não garante serviço ativo. Se o IP mudou, caches e TTL podem manter clientes em destinos diferentes.

Não faça varredura de portas em sistemas de terceiros. Teste somente o host e a porta que você administra ou tem autorização para diagnosticar.

Logs e correlação

No cliente, registre horário, URL sem segredo, endereço resolvido e mensagem. No servidor, registre início, bind, porta e desligamento. Se não há qualquer log de requisição, a conexão não chegou à aplicação.

Use horário com fuso ou UTC. Compare eventos de implantação, reinício, troca de DNS e firewall. A diferença entre “nunca iniciou” e “parou às 14:02” muda completamente a investigação.

Não publique saída contendo IP privado, token, cookie ou caminho de usuário sem revisão.

Teste automatizado de disponibilidade

import socket

def porta_aberta(host, port, timeout=3):
    try:
        with socket.create_connection((host, port), timeout=timeout):
            return True
    except OSError:
        return False

assert porta_aberta("127.0.0.1", 8080)

Esse teste confirma TCP, não saúde da aplicação. Para HTTP, solicite um endpoint de saúde que verifique somente dependências essenciais e devolva status coerente.

Monitore com frequência razoável e limite alertas. Testes agressivos podem virar carga desnecessária.

Ordem prática de diagnóstico

1. confirme esquema, host e porta;
2. reproduza com curl -v;
3. verifique se há processo escutando;
4. confirme bind IPv4/IPv6;
5. leia logs de início e encerramento;
6. teste proxy e origem separadamente;
7. valide contêiner e mapeamento;
8. examine firewall somente após o teste local;
9. repita a partir do cliente afetado.

Mapeie as camadas no criador de fluxogramas, consulte as ferramentas e organize resultados de múltiplas máquinas com o iatnGrid.

Em ambientes com vários serviços, execute o teste a partir de cada fronteira relevante. Uma aplicação no host pode acessar localhost:5432, mas um contêiner precisa usar o nome do serviço. Um proxy em outra máquina precisa alcançar o endereço privado anunciado, não o loopback da origem. Registre uma matriz:

Origem do teste	Destino	Resultado	Interpretação
próprio servidor	127.0.0.1:8000	aceita	processo local ativo
proxy	app:8000	recusa	rede, nome ou bind interno
navegador	site:443	aceita/502	borda ativa, origem falhando

Essa matriz impede que um teste local bem-sucedido seja usado como prova de todo o caminho.

Quando o serviço usa systemd, consulte estado e logs sem reiniciar primeiro:

systemctl status nome-do-servico --no-pager
journalctl -u nome-do-servico --since "15 minutes ago" --no-pager

Em Windows, use o console de Serviços ou comandos administrativos aprovados para conferir estado. Não altere o tipo de inicialização sem saber por que o serviço parou.

Uma porta pode mudar por variável de ambiente, argumento ou configuração. Registre na inicialização o endereço efetivo, mas não segredos. Se duas instâncias tentam a mesma porta, a segunda costuma registrar “address already in use”; isso é diferente de cliente recusado depois que a primeira também encerra.

Verifique dependências em ordem. Um servidor pode esperar banco, fila ou arquivo e decidir não iniciar. O log da dependência explica a causa; abrir firewall na porta HTTP não corrige credencial inválida do banco. Healthchecks devem distinguir “processo ativo”, “pronto para tráfego” e “dependências degradadas”.

Para serviços externos, teste o nome oficial e confirme a janela de manutenção antes de alterar a rede local. Se outros clientes também falham, preserve evidências e escale ao responsável. Não tente contornar por IP desconhecido ou porta alternativa não documentada.

Depois da correção, valide mais que uma conexão única. Reinicie de forma controlada, confirme que o processo volta, que a porta reaparece e que uma solicitação real recebe status esperado. Observe por alguns minutos para capturar encerramento tardio.

Documente causa, evidência e correção: “processo não iniciou porque variável PORT continha texto; validação adicionada e serviço agora escuta em 8000” é melhor que “rede corrigida”. Inclua teste preventivo e responsável pela configuração.

Em monitores, configure timeout de conexão separado do timeout de resposta. Um serviço pode aceitar TCP e travar durante HTTP. Essas falhas exigem alertas diferentes e evitam que ERR_CONNECTION_REFUSED seja usado como nome genérico para qualquer indisponibilidade.

Checklist final

Após restaurar o serviço, teste pelo mesmo caminho usado pelo usuário, não apenas por localhost. Confirme resolução DNS, certificado quando houver HTTPS, proxy, status HTTP e conteúdo mínimo esperado. Uma porta aberta pode servir a aplicação errada.

Registre um teste de prontidão para a próxima implantação e defina alerta separado para processo ausente e resposta lenta. Assim, uma recusa futura já chega acompanhada da camada provável, reduzindo tentativas aleatórias e mudanças emergenciais no firewall.

Se a solução envolveu alterar bind ou regra de rede, revise a superfície exposta. Mantenha somente origens e portas necessárias, autenticação ativa e documentação de reversão.

Repita o teste após reinicialização programada para confirmar que a configuração persiste e o serviço volta automaticamente conforme o desenho aprovado.

• URL, esquema e porta estão corretos;
• curl -v confirmou a etapa exata;
• existe processo ouvindo na porta;
• bind aceita a origem pretendida;
• IPv4 e IPv6 foram comparados;
• logs confirmam que o serviço permanece ativo;
• proxy aponta para host e porta internos corretos;
• contêiner está rodando e publica a porta certa;
• firewall foi analisado sem desativação ampla;
• VPN e proxy do sistema foram considerados;
• teste TCP não foi confundido com saúde HTTP;
• nenhuma varredura não autorizada foi realizada.

Documentação primária

• curl — manual oficial
• Python — socket.create_connection
• Docker — publicação de portas
• MDN — visão geral de HTTP
• IANA — registro de portas

Nota de produção

Rascunho autoral orientado à busca “ERR_CONNECTION_REFUSED como resolver”. Os laboratórios usam loopback e serviço local descartável. A revisão humana deve testar comandos por sistema operacional, validar políticas de rede e conferir os links antes da publicação.

Camada extra: como tomar uma decisão melhor neste cenário

Em uso real, ERR_CONNECTION_REFUSED: como descobrir se o problema é porta, serviço, proxy ou firewall costuma envolver mais de uma camada. O ganho de qualidade aparece quando cada camada tem uma pergunta de verificação antes de qualquer mudança definitiva.

**ERR_CONNECTION_REFUSED** significa que o navegador não conseguiu estabelecer conexão com o endereço e a porta de destino. Em geral, nenhum processo está escutando ali ou alguma camada rejeitou ativamente a tentativa. É diferente de timeou A ideia central pode ser testada com quatro perguntas: o que foi observado, qual hipótese explica o sintoma, qual mudança é reversível e qual evidência prova que funcionou. Esse encadeamento evita que uma coincidência seja confundida com causa e torna o procedimento repetível por outra pessoa.

Depure por camadas, não por palpites

Para redes, ERR_CONNECTION_REFUSED, curl, porta, uma mensagem de erro geralmente descreve o ponto em que a execução falhou, não necessariamente a causa inicial. Reduza o cenário até a menor reprodução possível e verifique ambiente, entrada, configuração, dependências e estado antes de alterar o código principal. Se duas mudanças são feitas ao mesmo tempo, você perde a capacidade de saber qual delas resolveu — ou qual criou o próximo defeito.

Registre versão da ferramenta, comando executado, trecho mínimo da entrada e saída observada. Em seguida, faça uma mudança reversível e repita exatamente o mesmo teste. Essa disciplina parece lenta durante cinco minutos e economiza horas quando o problema reaparece em outra máquina ou no ambiente de produção.

Matriz de diagnóstico

Camada	Sinal típico	Teste útil
Ambiente	Funciona em uma máquina e falha em outra	Comparar versões e variáveis
Entrada	Falha só com certos dados	Caso mínimo reproduzível
Estado	Falha intermitente	Logs, concorrência e sequência
Integração	Componente isolado funciona	Inspecionar fronteiras e contratos

Antes de considerar resolvido

Rode o caso que falhava, um caso normal e um caso-limite. Confirme logs limpos, ausência de regressão e comportamento previsível após reiniciar o processo. Se a correção depende de “rodar de novo até funcionar”, o diagnóstico ainda não terminou.

Checklist de fechamento

• Registre o estado inicial antes de alterar qualquer coisa.
• Faça uma mudança por rodada e anote o efeito.
• Teste um caso normal, um caso-limite e o cenário que originalmente falhou.
• Confirme que a solução continua válida depois de reiniciar, reabrir ou repetir o fluxo.
• Guarde uma forma de voltar ao estado anterior quando a alteração for destrutiva.

Esse método acrescenta profundidade sem transformar o artigo em teoria abstrata: o leitor entende por que cada passo existe e como reconhecer quando a situação exige uma decisão diferente.