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.
Name and connection errors
Section titled “Name and connection errors”| 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 |
TLS and certificate errors
Section titled “TLS and certificate errors”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 |
Redirects and HSTS
Section titled “Redirects and HSTS”| 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. |
HTTP status codes
Section titled “HTTP status codes”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 |
Cloudflare errors
Section titled “Cloudflare errors”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
Section titled “SSH errors”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 |
Docker and socket binding errors
Section titled “Docker and socket binding errors”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.
- Name. Does the name resolve to the address you expect?
dig +short pipeslab.indig +short app.pipeslab.inYou 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.
- 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.
ping -c 3 203.0.113.10- Route. Do packets reach the host and come back? Timeouts that stop partway along the path point at a route problem.
traceroute -n 203.0.113.10On the server, ip route shows the default route. A missing default route is a Route problem even though the app is fine.
- Door. Is anything listening on that port, on that address? Run these on the server, then from outside.
ss -tlnpnc -vz 203.0.113.10 443Refused means the packet arrived and the door is shut. Timed out means the packet never got an answer, so look at the Guard next.
- 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.
sudo ufw status verboseIf 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.
- 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.
sudo nginx -tsudo tail -n 50 /var/log/nginx/error.logopenssl s_client -connect app.pipeslab.in:443 -servername app.pipeslab.inIf 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.
- App. Is the app answering on its own port? Ask it directly from the server, skipping the proxy entirely.
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.
What to read next
Section titled “What to read next”/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.