lidge-jun/codexclaw / plugins/codexclaw/skills/dev-debugging
cxc-dev-debugging
VerifiedUse for debugging and system comprehension. Triggers: debug this, root cause, how does X work, reverse engineer, 왜 안 돼, 디버깅, 원인 분석, 로직 파악, 뜯어봐.
references/runtimes/js/node-backend.md
View on GitHub# Node Backend Debugging (Express / Fastify / NestJS)
Covers Express 5, Fastify 5, NestJS 11, plus cross-cutting Node server
diagnostics (AsyncLocalStorage, diagnostics_channel, heap snapshots).
Lineage: gpt-5.5 Tier-2 research (2026-07-07).
## Phase 0 — Environment Detection
```bash
node -v
npm ls express fastify @nestjs/core pino 2>/dev/null
npm pkg get scripts
env | grep -E 'DEBUG|NODE_OPTIONS|NODE_ENV'
```
## Express 5
- **Async rejections now auto-forward** to error middleware (as if `next(err)`
was called) — legacy `asyncHandler` wrappers are redundant and can
double-handle.
- **Router debug namespace moved**: router internals live in a separate
`router` package, so `DEBUG=express:*` alone is incomplete:
```bash
DEBUG=express:*,router,router:* node index.js
```
- **Route syntax trap**: bare `*` wildcards fail after migration — named
wildcards `/*splat` or `/{*splat}`; optional `?` markers move to braces.
## Fastify 5
- **Logging is off by default and CANNOT be enabled later** — construct with
`Fastify({ logger: { level: 'debug' } })` (pino).
- **Lifecycle tracing**: hooks run `onRequest -> preValidation -> preHandler ->
onSend -> onResponse` (onResponse fires after bytes sent — timing home):
```js
fastify.addHook('onRequest', async req => { req.start = performance.now() })
fastify.addHook('onResponse', async (req, reply) => {
req.log.debug({ ms: performance.now() - req.start, status: reply.statusCode })
})
```
- **Native diagnostics_channel** (v5): subscribe to
`tracing:fastify.request.handler:start/end/error` for low-intrusion traces.
- **Schema validation vs serialization are separate failure paths**: request
validation errors -> `attachValidation: true` + inspect
`req.validationError.validation`; response serialization SILENTLY DROPS
fields not in the response schema — compare raw handler return vs schema.
v5 requires full JSON Schema with `type` everywhere.
- Repro without a socket: `fastify.inject()`.
## NestJS 11
- **DI errors workflow** (UnknownDependenciesException): read the exact
provider/module/index in the message; check the provider is in `providers`,
the exporting module is imported, no circular file imports via barrels, no
duplicate `@nestjs/core` copies. `Object` as unknown token = interface/
type-only injection — use a concrete class or `@Inject(TOKEN)`.
- **Debug launch**: `nest start --debug --watch` (`--debug [hostport]` =
`--inspect`), or `npm run start:debug`.
- **REPL**: `npm run start -- --entryFile repl` — poke providers directly.
- **Devtools graph**: `@nestjs/devtools-integration` + `snapshot: true`;
never in production.
- `forwardRef` is a design smell escape hatch — only when the cycle is valid.
## Cross-Cutting Node Server Diagnostics
```bash
node --trace-uncaught --unhandled-rejections=strict index.js # rejection origins
node --heapsnapshot-signal=SIGUSR2 app.js # then: kill -USR2 <pid>, diff snapshots
```
- **AsyncLocalStorage context loss**: log `als.getStore()` after suspect
awaits/callbacks; wrap non-promise callbacks with `AsyncResource`.
- **diagnostics_channel** is the vendor-neutral instrumentation surface
(Fastify native; Sentry tracing channels ride it).
- Clinic.js is no longer actively maintained — prefer built-in heap snapshots
and `--cpu-prof`.
## Silent-Failure Patterns
| Symptom | Likely cause | First probe |
| --- | --- | --- |
| Express async route skips custom handling | Express 5 auto-forwards rejections | Confirm error middleware receives it |
| Fastify: no logs at all | Logger disabled at construction | Check `Fastify({ logger })` |
| Fastify: `request.body` undefined in early hook | Body not parsed until preValidation | Move probe to `preValidation`/`preHandler` |
| Fastify: response fields disappear | Response schema drops unlisted fields | Compare raw return vs response schema |
| Nest: `Object` unknown token | Type-only injection | Concrete class or `@Inject(TOKEN)` |
| Request ID disappears mid-flow | Async context loss | `als.getStore()` probes after each await |
| Promise failure lacks origin | Default rejection mode | `--unhandled-rejections=strict --trace-uncaught` |
| Memory grows only in prod server | Retained request data/listeners/cache | Heap snapshot diff via SIGUSR2 |
## Cleanup
```bash
unset DEBUG NODE_OPTIONS
# remove temporary hooks, diagnostics_channel subscribers, attachValidation,
# verbose logger levels, inspector ports, Devtools registration
git diff | rg 'addHook|attachValidation|logger.*debug|--inspect' | head
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |