Skip to content
Runtime

Node.js

Official site

Playbooks for Node.js

  1. Diagnosing Node.js ECONNREFUSED

    Confirms nothing is actually listening at the target address, then splits between a host/port misconfiguration (wrong address for where the dependency actually lives) and a startup-order race (the app connects before its dependency is ready). It does not cover connection timeouts (ETIMEDOUT), which point at network reachability rather than an actively refused connection, and it isn't specific to any one dependency — the same triage applies whether the target is a database, cache, or another service.

    Unverifiedno reproductions yetWhy this confidence?

  2. Freeing a port stuck with EADDRINUSE

    Identifies what actually holds the port, checks whether it's an orphaned instance of the same app versus a different legitimate service, and verifies the port is free afterward. It does not cover a port genuinely reserved by the OS or blocked by a firewall — EADDRINUSE specifically means something is bound, not that access is denied.

    Unverifiedno reproductions yetWhy this confidence?

  3. Diagnosing ERR_MODULE_NOT_FOUND after upgrading Node

    Node's ESM resolver rules around mandatory file extensions and 'exports' enforcement are not new in Node 22 — the summary is important here: the upgrade is usually the trigger only because it came with a lockfile/dependency refresh, not because Node itself changed how it resolves modules. Splits the failing specifier into your own relative import (missing extension) versus a dependency (its exports map tightened). It does not cover a plain 'Cannot find module' with no ERR_ prefix right after npm install — that's a CommonJS-style resolution failure covered by a separate playbook.

    Unverifiedno reproductions yetWhy this confidence?

  4. Diagnosing a missing module npm install silently didn't provide

    Confirms the module truly isn't installed, then checks the two most common install-time reasons: a platform-specific optionalDependency (native addons like esbuild/sharp binaries) skipped because the install environment's OS/architecture didn't match the runtime environment's, and a lockfile out of sync with package.json. It does not cover an ESM 'ERR_MODULE_NOT_FOUND' extension or exports-map error, which is a resolution-time problem with a package that IS installed, covered by a separate playbook.

    Unverifiedno reproductions yetWhy this confidence?

  5. Diagnosing a V8 heap-limit crash that isn't a container OOM-kill

    Covers telling a V8 heap-limit crash apart from a container/orchestrator OOM-kill (a different failure with no application log line at all), and the two independent responses: raising V8's ceiling versus finding a leak. Does not cover Kubernetes OOMKilled pod eviction — that's a distinct failure mode, at a different layer, with its own playbook, even though both are commonly described as 'ran out of memory'.

    Unverifiedno reproductions yetWhy this confidence?

Versions