Skip to main content
network-tools

Port Checking for Self-Hosted Services: A Practical Debug Guide

Your VPS is up, the DNS resolves, the app was "deployed successfully" — and the browser still shows a timeout. Nine times out of ten, the answer sits in a port: something is listening on the wrong interface, a firewall is eating the packets, or a container never published the port at all. A 30-second port check sorts most of this out, if you know how to read the result.

Three different failures that look the same

A port check has three possible outcomes, and each one points a completely different direction:

  • Open. Something accepted a TCP handshake on that host and port. The network path works; whatever is wrong lives at the application layer.
  • Refused. The host answered with a TCP RST. This is the informative one: the machine is reachable and explicitly says nothing is listening there. Your packet traveled fine — the service either crashed, or it never started, or it bound to a different interface.
  • Timeout (filtered). No answer at all. Usually a firewall is silently dropping packets, or the host is genuinely offline, or a middle box swallows the traffic.

The most common debugging mistake is treating "refused" and "timeout" as the same problem. They are not. Refused means stop looking at the network and look at the process. Timeout means stop looking at the process (you cannot even reach it) and look at the firewall or the route.

The localhost trap

This one catches everyone at least once. The service runs, curl localhost:8080 works on the server itself, but the TCP port checker from outside reports the port as closed or refused. The classic cause: the process bound to 127.0.0.1 instead of 0.0.0.0.

You see this everywhere once you know the pattern:

  • A dev server started with --host localhost or no host flag at all.
  • Docker run with -p 127.0.0.1:5432:5432 — the container port is only reachable from the host itself, which is often intentional (a private database) and often a mistake (everything else you wanted to deploy on the same box).
  • Databases that ship with safe defaults: PostgreSQL listens on localhost out of the box, and people forget to change listen_addresses in postgresql.conf.

On the server, ss -tlnp tells the truth in one line: if the local address column shows 127.0.0.1:8080, no external client will ever connect, no matter what the firewall says. It needs to read 0.0.0.0:8080 (all interfaces) or the server's actual LAN/public IP.

Firewall: DROP versus REJECT matters

Two firewall rules can both block you, but they fail differently:

  • REJECT sends back an RST (or ICMP port-unreachable). The client sees "refused" immediately.
  • DROP discards the packet silently. The client waits, retries, and times out. This is what default ufw and most cloud security groups do.

So: refused → the firewall lets you through but nothing listens. Timeout → probably a firewall drop before you ever reach the port. When the port check times out, the fix is usually one missing rule — ufw allow 8080/tcp, or an inbound rule in the cloud provider's security group. People spend hours restarting services for what is a one-line firewall change.

One more trap: cloud providers put a second firewall outside your server. AWS security groups, Hetzner Cloud firewalls, Oracle's default rules — those block at the hypervisor level, and no amount of ufw poking on the VM itself will fix them. Checking the port from outside is the only way to see that layer's opinion.

Checking from the wrong place

The second classic mistake: testing the port on the server and concluding it works. nc -zv example.com 8080 executed on the server itself often goes out and back through the loopback or the same firewall interface in a way that never exercises the real path. A security group that only allows inbound from the same VPC will look perfectly open from inside the VPC and time out from the outside world.

Always verify from a vantage point that matches what your users do — that means the public internet. Run the check from a different network and treat "works from the server itself" as evidence of nothing.

When the port is open but the site is still down

Open port, and the browser still fails? Now the network is proven good and the suspects change:

  • TLS problems. Port 443 open but the certificate expired or the chain is broken — the browser kills the connection with a security error while every port check happily says "open". An SSL certificate check at the same time as the port check catches this in seconds.
  • Health check passes but app fails. The reverse proxy answers with 502/504 because the upstream app crashed even though nginx's ports are wide open. Port 80 open says the proxy lives; it says nothing about the app behind it.
  • Wrong port entirely. The app moved to 3000, the check targets 80. Sounds silly, happens constantly after a config refactor.

A quick HTTP availability check on top of the port result separates "is the door open" from "is there a person behind it".

A triage order that works

Next time a self-hosted service is unreachable, run this sequence instead of poking at random config files:

  1. Ping the host — establishes the machine is alive. But remember some servers drop ICMP by design, so a failed ping is not proof of death. A ping tool result is a hint, not a verdict.
  2. Check the specific port. Open → skip to the application layer (logs, TLS, proxy). Refused → the process: is it running, what did it bind to, ss -tlnp. Timeout → the firewall on the VM and in the cloud console.
  3. Check the TLS layer if the port is 443 and you get a browser security error rather than a network error.
  4. Check HTTP response codes once connectivity is proven — 502 and 504 mean your problem moved upstream of the proxy.

Four steps, under five minutes, and each step eliminates a whole class of causes before you look at a config file. It is not glamorous, but it turns "why is the site down" from an hour of guessing into a two-minute decision tree.

Keep it boring

Port checking is one of those tools that pays for itself in the first incident: no agent to install, no SSH into a half-dead box, no "works on my machine". Make it part of the first five minutes of every outage — before restarting anything, before reading a single log line. Half of failed deployments are, in reality, ports that nobody opened.