Skip to content

Appendix E — Error Message Decoder

Errors are sentences spoken by one rung of the stack. The words give you the symptom. The sender and the layer tell you where to look. Each row names the rung the message usually points to, using the book’s mantra: Name → Address → Route → Door → Guard → Receptionist → App. The first check is the cheapest command that can confirm or kill the theory.

Examples use the lab’s documentation addresses (203.0.113.10 and pipeslab.in), so copy the shape, not the value.

For the ideas behind each rung, read Chapter 1, Addresses and Chapter 3, Ports. Port numbers live in Appendix A.

Message What it means Layer First check
ERR_NAME_NOT_RESOLVED Your machine could not turn the hostname into an address at all. Name dig +short app.pipeslab.in on the same machine
NXDOMAIN The resolver got a clean answer: this name does not exist. Name Check for a typo, then dig +trace app.pipeslab.in to see the record at its source
SERVFAIL The resolver tried and could not get a valid answer. Often a broken delegation or a DNSSEC mismatch. Name dig +trace, then try a different resolver to rule out your own
connection refused (ECONNREFUSED) The packet arrived and got an immediate no. Nothing listens on that port, or it listens only on 127.0.0.1, or a firewall sends a reset. Door On the server, ss -tlnp, then read the bind address
connection timed out (ETIMEDOUT, ERR_CONNECTION_TIMED_OUT) Packets went out and nothing came back. A silent drop, a wrong IP, or a host that is off the network. Guard, or Route nc -vz 203.0.113.10 443 from outside, then the cloud firewall and ufw
connection reset by peer (ECONNRESET) The conversation was open and the other side slammed it shut. Usually an app that crashed mid-request, or a proxy that gave up on its upstream. App Logs from the app and the proxy, same minute
no route to host (EHOSTUNREACH) The kernel has a path, but the next hop never answered. Often a LAN address on the wrong network, or ARP failing. Route ip route get 10.0.0.5 on Linux, route -n get 10.0.0.5 on macOS
network is unreachable (ENETUNREACH) Your machine has no route at all to that network. Often no default gateway, or a VPN that dropped its routes. Route Read the routing table, then check the VPN or tailnet is up
ERR_CONNECTION_CLOSED The server closed the connection before sending a response. Often a proxy dropping an idle keep-alive, or an HTTP and TLS mismatch. Receptionist curl -v the URL, then the proxy error log for that minute

The padlock has its own rung. TLS sits between the door and the app, and its errors usually point at the receptionist, the one who checks the badge before anyone goes in.

Message What it means Layer First check
ERR_SSL_PROTOCOL_ERROR The browser tried TLS and got something that is not TLS back. Often plain HTTP answering on 443, or a TLS version the server refuses. Door curl -vI https://app.pipeslab.in and read the handshake lines
SSL_ERROR_RX_RECORD_TOO_LONG Firefox’s name for the same thing: it read a plain-text reply where it expected TLS. Door Same as above, then check which service owns port 443 with ss -tlnp
NET::ERR_CERT_COMMON_NAME_INVALID / SSL_ERROR_BAD_CERT_DOMAIN The certificate is real but names other hosts. The receptionist handed you the wrong office’s badge. Receptionist openssl s_client -connect 203.0.113.10:443 -servername app.pipeslab.in and read the subject and SAN list
NET::ERR_CERT_DATE_INVALID Certificate expired, or not yet valid. Sometimes the clock on the server or your laptop is what is wrong. Receptionist openssl x509 -noout -dates on the certificate, then the clock with timedatectl
ERR_CERT_AUTHORITY_INVALID The chain does not lead to a root your browser trusts. Self-signed, a missing intermediate, or a corporate proxy re-signing traffic. Receptionist openssl s_client and look for a missing intermediate; retry in a clean browser profile
Message What it means Layer First check
ERR_TOO_MANY_REDIRECTS A loop. HTTP to HTTPS and back, www to apex and back, or the app sends you to login which sends you back to the app. Receptionist or App curl -sIL --max-redirs 5 https://app.pipeslab.in and read each Location header
HSTS: “This site uses HSTS” or a cert error with no way past it Your browser remembers that this host is HTTPS only, and a certificate fault under HSTS has no click-through. Receptionist Fix the certificate. HSTS expires on its own schedule, set by max-age.

Status codes are the receptionist’s answers. The number tells you the class of answer. The body and the Server or Via header tell you which office spoke.

Code What it means Layer First check
400 “plain HTTP request sent to HTTPS port” You sent plain HTTP to the TLS door. Often a health check or a curl typed without https. Door Retry with https://, then fix the probe
400 (generic) The request was malformed: bad header, bad encoding, or a proxy refusing it. Receptionist The proxy log line for the same request
403 Someone knows who you are and says no. File permissions, an access rule, a WAF rule, or an app authorisation check. Guard or App Read the sender: nginx error.log says why; Cloudflare shows rule IDs in security events
404 from the proxy The default page of nginx or Caddy. No server_name or location matched, so the app never saw the request. Receptionist nginx -T and check the server_name against the Host header you sent
404 from the app The request reached the app and the app has no such route. App Hit the same path with curl and check the app’s route list
413 Payload Too Large The body is bigger than the proxy allows. nginx’s default client_max_body_size is small. Receptionist Raise the limit in the proxy config, test, reload
421 Misdirected Request The connection was reused for a host the certificate does not cover. Common with HTTP/2 and shared IPs. Receptionist Which hostname did the browser use? Reload the page to open a fresh connection
499 (nginx log only) The client gave up before nginx replied. Usually a slow upstream the visitor stopped waiting for. Receptionist Upstream timing in the same log line. Not a server fault by itself.
500 The app threw an exception it did not catch. App App logs for that request, matched by time or request ID
502 Bad Gateway The proxy reached the upstream and got a broken reply, or no process was listening there. Door (app side) curl -I http://127.0.0.1:3000 on the box, then ss -tlnp
503 The upstream is up but declining: maintenance mode, overloaded, or a failing health check. App The app’s health endpoint, then load
504 Gateway Timeout The proxy waited for the upstream and gave up. A stuck query or a hung worker. App Upstream response time in the proxy log, then the slow query or endpoint

These appear when the request reached Cloudflare, but Cloudflare could not finish the trip to your origin. The orange-cloud page is Cloudflare’s opinion. The origin may be fine, or it may be the reason. Check both.

Code What it means Layer First check
520 The origin answered, but with something Cloudflare could not parse: an empty reply, a broken header, or a reset. App Origin logs for that request, then curl -I against the origin directly
521 Cloudflare could not open a connection to the origin at all. Nothing listens, or the port refuses. Door ss -tlnp on the server, then the origin port in your DNS record
522 Cloudflare connected, then the origin never finished the handshake in time. Often a firewall dropping Cloudflare’s addresses. Guard Cloud firewall and ufw on 443, then retest
523 Cloudflare reached the address you gave it, but the origin host is not there. The IP is wrong, or the box is down. Address Compare the A record with the server’s real public IP in the provider console
524 Connected, request sent, and the origin did not reply before Cloudflare gave up. Roughly 100 seconds on most plans. App Upstream timing in the proxy log, then the slow endpoint
525 The TLS handshake between Cloudflare and the origin failed. The origin’s TLS setup does not match what Cloudflare expects. Receptionist openssl s_client -connect 203.0.113.10:443 -servername app.pipeslab.in
526 Strict SSL mode: the origin’s certificate is invalid, expired, or names other hosts. Receptionist openssl x509 -noout -dates on the origin certificate, then its SAN list
530 The origin could not be reached through a tunnel. Read the body: the error code inside it says which kind. Door Whether cloudflared is running on the box, then its log for that minute
1033 Tunnel error: no cloudflared connector is up for this hostname. Shows as a 530 page. Door systemctl status cloudflared, then the tunnel’s health in the Cloudflare dashboard
1020 Access denied by a Cloudflare firewall rule. The request never reached your origin. Guard Security events in the dashboard, then the rule ID shown there

SSH errors are the most candid in this book, because ssh and sshd say which side refused. A plain timeout on port 22 is not an SSH error at all. It is the connection timed out row above, and the triage starts at the Guard.

Message What it means Layer First check
Permission denied (publickey) sshd is up and reached the login step, but none of the keys you offered is in that user’s authorized_keys. Wrong user, wrong key, or wrong file permissions. App (sshd) ssh -v ops@203.0.113.10 to see which keys were offered, then sudo journalctl -u ssh on the server
Host key verification failed Your client does not trust the host key it was shown. There is no entry in known_hosts, or the entry is different. Receptionist ssh-keygen -F 203.0.113.10 to see what your machine remembers
REMOTE HOST IDENTIFICATION HAS CHANGED The server’s host key differs from the one you saved. Usually a rebuilt server or a reused IP. Occasionally a man in the middle. Receptionist Check the fingerprint in the provider console first. Only then run ssh-keygen -R 203.0.113.10
Connection closed by remote host sshd accepted the connection, then hung up mid-conversation. Often MaxStartups under load, a ban after failed logins, or an AllowUsers rule. Guard or App sudo journalctl -u ssh for that minute, then sudo fail2ban-client status sshd if fail2ban runs
Too many authentication failures Your agent offered several keys, and the server gave up before it reached the right one. Your client is the problem, not the server. App (your client) ssh -v to count the offered keys. Fix with IdentitiesOnly yes and -i for the right key

Binding errors are doors that are already occupied, or doors you are not allowed to open. The message names the port. The first check names the owner.

Message What it means Layer First check
Bind for 0.0.0.0:3000 failed: port is already allocated Docker cannot publish that host port. Another container, or a host process, already holds it. Door docker ps for the port, then ss -tlnp on the host for the owner
address already in use (EADDRINUSE) Your process tried to bind a port that another process holds. Inside a container, the port belongs to that container’s own network space. Door ss -tlnp and read the PID. Check whether an old copy of the app is still running
permission denied when binding a port below 1024 Only root, or a process given the right capability, may bind a port below 1024. Your app runs as a normal user. Door id to see the user. Bind a high port such as 3000, and let nginx or Caddy own 80 and 443

Triage order: Name → Address → Route → Door → Guard → Receptionist → App

Section titled “Triage order: Name → Address → Route → Door → Guard → Receptionist → App”

When something fails, start at the left and stop at the first rung that fails. Each rung has one cheap check, and you should run them in this order. Skipping ahead is how you spend an evening on a firewall that was never the problem.

  1. Name. Does the name resolve to the address you expect?
Terminal window
dig +short pipeslab.in
dig +short app.pipeslab.in

You want 203.0.113.10, or Cloudflare’s addresses if the record is proxied. An empty answer or NXDOMAIN means you stop here and fix the record.

  1. Address. Is the host up, and does it still have the address you think it has? Check the provider console first, because a stopped VPS or a changed public IP explains a lot. Ping is a hint only, since many hosts drop ICMP.
Terminal window
ping -c 3 203.0.113.10
  1. Route. Do packets reach the host and come back? Timeouts that stop partway along the path point at a route problem.
Terminal window
traceroute -n 203.0.113.10

On the server, ip route shows the default route. A missing default route is a Route problem even though the app is fine.

  1. Door. Is anything listening on that port, on that address? Run these on the server, then from outside.
Terminal window
ss -tlnp
nc -vz 203.0.113.10 443

Refused means the packet arrived and the door is shut. Timed out means the packet never got an answer, so look at the Guard next.

  1. Guard. Is a firewall dropping the packet? A port needs to be open in both places: the cloud firewall (the Oracle Cloud security list or network security group) and the host firewall.
Terminal window
sudo ufw status verbose

If the cloud rule is open and the host rule is closed, or the other way round, you get a timeout that looks like a dead server. Fix one, test, then fix the other.

  1. Receptionist. Is the reverse proxy up, and does it send this host name to the right app? Validate the config, read its error log, and check the certificate it presents.
Terminal window
sudo nginx -t
sudo tail -n 50 /var/log/nginx/error.log
openssl s_client -connect app.pipeslab.in:443 -servername app.pipeslab.in

If you run Caddy, check its status and logs with systemctl status caddy and journalctl -u caddy. A 502 or 503 from here means the receptionist is fine but has nobody to hand the visitor to.

  1. App. Is the app answering on its own port? Ask it directly from the server, skipping the proxy entirely.
Terminal window
curl -i http://127.0.0.1:3000/

Use your app’s real port in place of 3000. If this works and the public path does not, the fault is in the receptionist (step 6). If this fails, the office is closed or broken, so read its logs with journalctl -u your-service -n 50 or docker logs --tail 50 CONTAINER.

Two habits make this order stick. First, test from outside as well as inside, because “works on localhost” is cursed and tells you about only the last two rungs. Second, read the sender before you start: the layer that printed the message tells you which rung to begin with.

  • /part-2/ch06-ssh/ for the SSH errors and the key trail
  • /part-3/ch08-reverse-proxies/ and /part-3/ch09-https/ for the receptionist and the certificate
  • /part-5/ch14-firewalls/ for the guard and the timeouts it causes
  • /part-5/ch17-cloudflare/ for the 52x and 1033 family
  • /appendices/c-nginx-caddy/, /appendices/d-ssh/, /appendices/f-hardening/, and /appendices/g-glossary/ for config, SSH, hardening, and terms

Book 2 of a series. Book 1: The Glue.