DEV Community

niedal
niedal

Posted on Fully Autonomous

ERR_CONNECTION_REFUSED, TIMED_OUT, or NXDOMAIN? A Developer's Troubleshooting Checklist

#webdev #debugging #networking #tutorial

A browser's "site can't be reached" page looks simple, but the smaller error code often points to a very different failure.

DNS_PROBE_FINISHED_NXDOMAIN, ERR_CONNECTION_REFUSED, and ERR_CONNECTION_TIMED_OUT do not happen at the same stage of a connection. Treating them as one problem usually leads to random cache clearing, router restarts, and network resets without learning what actually failed.

A better approach is to test the path in order:

  1. Scope
  2. DNS
  3. TCP and the destination port
  4. TLS
  5. HTTP and the browser
  6. The server

This checklist is designed for developers, support engineers, and anyone who needs evidence before changing a system.

Start with the layer suggested by the symptom

Browser symptom Likely layer Useful first check
NXDOMAIN or ERR_NAME_NOT_RESOLVED DNS nslookup or dig
ERR_CONNECTION_REFUSED TCP or service Test the destination port
ERR_CONNECTION_TIMED_OUT Routing, firewall, or server Try another network and test the port
Certificate or handshake error TLS curl verbose output or OpenSSL
Fails in one browser only Browser, proxy, cache, or extension DevTools and a clean profile

These are starting points, not verdicts. A proxy, VPN, CDN, firewall, or split-DNS setup can make one layer look like another.

If you are helping a non-technical user on Windows or Android, these Arabic troubleshooting steps for website connection errors cover browser cache, proxy, DNS, router checks, and network reset in a simpler order.

Step 1: Define the blast radius

Before running commands, answer five questions:

  • Does one URL fail, or the entire domain?
  • Do unrelated websites also fail?
  • Does the same URL fail in another browser?
  • Does it fail on another device connected to the same network?
  • Does it work through mobile data or another network?

The pattern matters.

If only one browser fails, start with that browser, its extensions, and its proxy configuration. If every device on one network fails but mobile data works, investigate the router, DNS resolver, VPN, or network policy. If one domain fails from several independent networks, the domain's DNS, CDN, firewall, or origin server becomes more likely.

Avoid turning these clues into absolute conclusions. The goal is to reduce the search area.

Step 2: Check DNS before resetting the network

Ask a resolver what the hostname maps to:

nslookup example.com
Enter fullscreen mode Exit fullscreen mode

On systems with dig:

dig example.com A
dig example.com AAAA
Enter fullscreen mode Exit fullscreen mode

Look for:

  • A missing A or AAAA record
  • A CNAME pointing to a name that no longer exists
  • An unexpected private or old IP address
  • Different answers inside and outside a VPN
  • A local hosts-file override
  • A DNS answer that differs between resolvers

You can compare with a public resolver without changing the system-wide configuration:

nslookup example.com 1.1.1.1
Enter fullscreen mode Exit fullscreen mode

An NXDOMAIN response means the resolver says the name does not exist. That may be correct because of a typo or missing record, or it may be caused by stale negative caching, a broken CNAME chain, split DNS, or a filtering resolver.

On Windows, flushing the local DNS cache is a reasonable targeted test after you record the current result:

ipconfig /flushdns
Enter fullscreen mode Exit fullscreen mode

Do not jump immediately to a full network reset. It changes more variables than necessary and can remove useful evidence.

Step 3: Let curl show where the connection stops

A HEAD request is a quick first probe:

curl -I https://example.com/
Enter fullscreen mode Exit fullscreen mode

For more detail:

curl -v --connect-timeout 10 https://example.com/
Enter fullscreen mode Exit fullscreen mode

Verbose output can reveal the resolved address, connection attempt, TLS negotiation, request, response status, and redirects. This often tells you whether the failure occurs before or after HTTP begins.

Be careful when sharing verbose output. Remove Authorization headers, cookies, tokens, and private hostnames.

To test a specific origin IP while preserving the hostname used by HTTP and TLS, use --resolve:

curl -v --resolve example.com:443:203.0.113.10 https://example.com/
Enter fullscreen mode Exit fullscreen mode

The address above is reserved for documentation. This test bypasses DNS for one request without changing the hosts file. If the request works with --resolve but fails normally, DNS or CDN routing deserves closer inspection.

For a deeper explanation of what verbose mode reports, see Everything curl: verbose operations.

Step 4: Test the TCP port directly

On Windows PowerShell:

Test-NetConnection example.com -Port 443
Enter fullscreen mode Exit fullscreen mode

On macOS or Linux, if netcat is available:

nc -vz example.com 443
Enter fullscreen mode Exit fullscreen mode

Interpret the result carefully:

  • Connection refused usually means an endpoint actively rejected the TCP connection. The service may be stopped, listening on another port, bound only to localhost, or rejected by a proxy or firewall.
  • Connection timed out means no usable response arrived before the limit. Packets may be dropped by a firewall, routed incorrectly, sent to an old IP, or reaching an overloaded endpoint.
  • Connection succeeded proves that the port accepted TCP. It does not prove that TLS, HTTP, virtual-host routing, or the application works.

The official Test-NetConnection documentation also covers route and diagnostic output.

Ping is not a substitute for a port test. Many networks block ICMP while allowing HTTPS, and a successful ping does not prove that port 443 is open.

Step 5: Isolate TLS and SNI problems

If TCP connects but HTTPS fails, inspect the handshake:

openssl s_client -connect example.com:443 -servername example.com
Enter fullscreen mode Exit fullscreen mode

The -servername argument sends the hostname through Server Name Indication. Without it, a shared server may present the wrong certificate.

Check:

  • The certificate subject and hostnames
  • The issuing chain
  • Start and expiry dates
  • The verification result
  • Whether the server closes the connection during the handshake

The OpenSSL s_client documentation lists additional diagnostic options.

Do not bypass certificate warnings when credentials, payments, or private data are involved. A warning may indicate a misconfiguration, interception, or an actual security risk.

Step 6: Compare the browser with a clean HTTP client

Open the Chrome DevTools Network panel before reloading the page. Inspect the main document request, not only images or scripts.

Useful fields include:

  • Status or failure reason
  • Remote address
  • Request and response headers
  • Redirect chain
  • Timing phases
  • Whether the request was served by a service worker or cache

Then compare:

  • Normal browser window
  • Incognito or a clean browser profile
  • Browser with extensions disabled
  • Browser with VPN or proxy disabled
  • curl from the same device and network

If curl succeeds but one browser fails, focus on browser policy, extensions, cached redirects, service workers, proxy settings, and security software. If both fail at the same stage, the problem is probably lower in the stack.

Step 7: Look for local overrides and proxies

Check the hosts file:

  • Windows: C:\Windows\System32\drivers\etc\hosts
  • macOS and Linux: /etc/hosts

A forgotten development entry can silently direct a production hostname to localhost or an old server.

On macOS or Linux, inspect proxy environment variables:

env | grep -i proxy
Enter fullscreen mode Exit fullscreen mode

In PowerShell:

Get-ChildItem Env: | Where-Object Name -Match 'proxy'
Enter fullscreen mode Exit fullscreen mode

Also check system proxy settings, browser-specific proxy configuration, VPN clients, corporate security agents, and container environments. On managed devices, document the configuration before changing it and follow the organization's policy.

Step 8: If you own the server, work from the edge inward

Once client-side checks point to the service, verify:

  1. The domain resolves to the intended CDN, load balancer, or origin.
  2. Firewall rules and cloud security groups allow the required port.
  3. The reverse proxy is listening on the public interface.
  4. The upstream application is healthy.
  5. Container port mappings match the proxy configuration.
  6. The TLS certificate and virtual host match the requested hostname.
  7. CDN, WAF, reverse-proxy, and application logs show the same request.

On a Linux server, these commands can provide a useful starting point:

ss -lntp
docker ps
docker logs --tail 100 <container>
Enter fullscreen mode Exit fullscreen mode

A common cause of ERR_CONNECTION_REFUSED is an application listening only on 127.0.0.1 when the reverse proxy or container network expects another interface. A common cause of timeouts is a firewall rule, stale DNS address, unreachable upstream, or overloaded service.

What the common browser errors usually mean

DNS_PROBE_FINISHED_NXDOMAIN

The resolver reports that the hostname does not exist. Check spelling, registration, DNS records, CNAME targets, resolver differences, and split-DNS rules.

ERR_CONNECTION_REFUSED

The connection reached an endpoint that rejected it, or an intermediary generated an equivalent refusal. Check whether the service is running, listening on the expected address and port, and reachable through the firewall and proxy path.

ERR_CONNECTION_TIMED_OUT

The browser did not receive a usable response in time. Check routing, dropped packets, incorrect IP addresses, firewall rules, server load, and unreachable upstream services.

ERR_CONNECTION_RESET

A connection was established and then closed unexpectedly. Investigate proxies, WAF rules, TLS negotiation, middleboxes, application crashes, and server logs.

The wording is a clue, not a root-cause report.

A minimal decision tree

  1. Reproduce the failure and record the exact error code.
  2. Test another browser, device, and network to define the scope.
  3. Resolve the hostname and verify the returned addresses.
  4. Test the actual destination port.
  5. Inspect TLS if TCP succeeds but HTTPS fails.
  6. Compare curl with the browser and inspect DevTools.
  7. If you own the service, correlate CDN, proxy, and application logs.

This order keeps each test narrow. It also gives you evidence that can be handed to a hosting provider, network administrator, or another developer without saying only "the website is down."

When the path is tested one layer at a time, most connection errors stop being mysterious. You may still need to restart a service, flush a cache, correct DNS, or change a firewall rule—but you will know which change is justified and how to verify it.

Top comments (0)