Chapter 3 — Error Codes Below Your App

ECONNRESET, Exit Code 137, SQLSTATE 23505 — and What Each One Physically Means

Part 1: Foundations. Prerequisites: Chapters 1–2.

Opening

Your JavaScript runs on top of a stack of other systems: the operating system, the network, TLS, the container or process manager, the database. When one of them fails, it reports the failure with a code — short, cryptic, and extremely precise.

ECONNREFUSED and ETIMEDOUT both mean "could not connect", but they describe completely different physical situations and send you to completely different places. Exit code 137 and exit code 134 both mean "the process died", but one means the container ran out of memory and the other means the JavaScript heap did. SQLSTATE 40001 means "retry this", while 23505 means "never retry this."

This chapter decodes the codes you will see most. The goal is a reflex: see the code, know the layer, know where to look — before opening a single file.

Part 1: Where These Codes Come From

When Node asks the operating system to do something — open a file, connect a socket, listen on a port — it makes a system call (syscall). If the syscall fails, the OS returns an error number called an errno, which has a symbolic name like ECONNREFUSED. Node puts that name on the error as err.code.

Read a Node system error as a sentence:

Error: connect ECONNREFUSED 127.0.0.1:5432
         │       │            └── the address and port it tried
         │       └── the code: what went wrong
         └── the syscall: what Node was trying to do

The error object also carries these as fields: err.syscall ('connect'), err.code ('ECONNREFUSED'), err.address and err.port. "Connect refused to port 5432" already tells you it is Postgres and that the problem is before any query ran.

The E prefix means "error". The rest is an abbreviation: CONNREFUSED = connection refused, NOENT = no entry (no such file), ACCES = access denied, ADDRINUSE = address in use.

Part 2: Network Codes — Mapped to the Life of a Connection

A network request goes through stages. Each code belongs to a stage, and knowing the stage tells you where to look.

Stage 1 — DNS lookup fails

Stage 2 — TCP connect fails

The difference between refused and timed out is the most useful distinction in network debugging. Refused is fast and means "reached the machine, nobody home." Timed out is slow and means "never reached anything that answered." A refused connection points at the service; a timeout points at the network path.

Stage 3 — the connection existed, then broke

Node's fetch wraps all of these

Node's built-in fetch (powered by a library called undici) throws a generic TypeError: fetch failed and puts the real error in cause:

TypeError: fetch failed
  [cause]: Error: connect ECONNREFUSED 127.0.0.1:3000

It also has its own codes, prefixed UND_ERR_: UND_ERR_CONNECT_TIMEOUT (connect took too long), UND_ERR_HEADERS_TIMEOUT (connected, but the server took too long to start responding), UND_ERR_SOCKET (the socket failed). If your error handling only logs err.message, every one of these looks identical: "fetch failed". Always log err.cause.

The keep-alive race — where mysterious ECONNRESETs come from

HTTP clients keep connections open after a request (keep-alive) so the next request can skip the TCP and TLS handshakes. Servers close idle connections after a timeout — Node's HTTP server defaults to 5 seconds. If the client picks an idle connection from its pool at the exact moment the server closes it, the request dies.

The same race between a load balancer and your app produces intermittent 502 errors, which Chapter 13 investigates in full.

Part 3: Filesystem, Port and Process Codes

Node's own ERR_ codes

Node also has codes for its own errors, prefixed ERR_. The ones you will meet most:

Part 4: TLS and Certificate Errors

HTTPS adds a TLS handshake after TCP connect. During it, the client checks the server's certificate: is it signed by a trusted authority, is it still valid, and does it match the hostname? Each failure has its own code.

Never "fix" these with NODE_TLS_REJECT_UNAUTHORIZED=0. It turns off certificate checking for the whole process, which means you will happily talk to an attacker. Fix the certificate, or give Node the right CA with NODE_EXTRA_CA_CERTS.

Part 5: Chrome's net::ERR_ Codes

In the browser, network failures show up in the Console and Network tab as net::ERR_…. They map almost one-to-one onto the Node codes above.

Part 6: Process Exit Codes and Signals

When a process ends, it reports an exit code: 0 means success, anything else means failure. When a process is killed by a signal, the exit code is 128 + the signal number. This is how you tell "the app crashed" from "something killed the app."

134 versus 137 matters. 134 means the V8 heap hit its limit (--max-old-space-size) — a JavaScript memory problem. 137 means the whole process exceeded the container's memory limit — which can include native memory, buffers and the heap together. In Kubernetes, the pod status shows OOMKilled for the second case.

Two more terms you will hear around containers:

• CrashLoopBackOff (Kubernetes) — the container keeps crashing on startup, so Kubernetes waits longer and longer between restarts. The cause is in the logs of the previous crashed container (kubectl logs --previous).
• Graceful shutdown — handling SIGTERM by stopping new work, finishing current requests and closing connections. Without it, every deploy cuts off in-flight requests, which shows up as a burst of 502s and ECONNRESETs at deploy time.

Part 7: Database Error Codes — PostgreSQL SQLSTATE

Postgres reports every error with a five-character SQLSTATE code (in Node, err.code). The first two characters are the class, and the class alone tells you a lot.

The specific codes you will actually meet:

Some database errors come from the client library or pool, not from Postgres, so they have no SQLSTATE: timeout exceeded when trying to connect (the pool had no free connection in time — usually pool exhaustion), and Connection terminated unexpectedly (the server or network dropped the connection). These are covered in Chapter 9.

Part 8: From Code to Layer — The Reflex

The point of this chapter is one reflex: the code tells you which layer to look at.

The Causal Chains

The Rule You Keep Forever

A code is a precise statement about which layer failed and how. Read the code first, decide the layer, and only then open the code that lives in that layer.

Vocabulary Map

Practice Problems

Problem 1 — Refused or timed out? Your app cannot reach Redis. In one environment the error appears instantly as ECONNREFUSED; in another it appears after 10 seconds as ETIMEDOUT. For each, name two likely causes and the first command you would run.

Problem 2 — The container question. A Node API in a container is restarted every few hours. The orchestrator shows exit code 137. A teammate wants to raise --max-old-space-size. Is that the right first move? What evidence would tell you whether the problem is the JS heap or total process memory?

Problem 3 — Read the transaction. Logs show current transaction is aborted, commands ignored until end of transaction block thousands of times, all from one endpoint. What is the very next thing you search the logs for, and why?

Problem 4 — Retry or not? For each, say whether an automatic retry is correct and why: (a) 40P01 deadlock_detected; (b) 23505 unique_violation on POST /signup; (c) ECONNRESET on a GET; (d) ECONNRESET on POST /payments.

Problem 5 — Same error, two worlds. A partner's HTTPS API works in Chrome but your Node service gets UNABLE_TO_VERIFY_LEAF_SIGNATURE. Explain why the behaviour differs, and what you would tell the partner.

What's Coming Next

Most of your debugging traffic speaks HTTP, and HTTP has its own codes: 401, 403, 429, 502, 504. Chapter 4 decodes the status codes — and teaches the skill most engineers miss: working out which hop in the chain actually sent the status. A 502 from your load balancer and a 502 from your own code mean completely different things.