# Node Debugging

> Debug Node.js backend processes using non-blocking tracepoints, logpoints, exceptionpoints, and JavaScript execution. Use when debugging API servers, workers, or backend scripts.

- Skill: `serkan-ozal/node-debugging` (Agent Skill)
- Install (CLI): `npx skillmds@latest add serkan-ozal/node-debugging`
- Raw SKILL.md: https://api.skillmd.com/api/skills/serkan-ozal/node-debugging/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: serkan-ozal (https://skillmd.com/u/serkan-ozal)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/serkan-ozal/node-debugging

---


# Node.js Backend Debugging Skill

Debug Node.js backend processes using non-blocking tracepoints, logpoints, exceptionpoints, and JavaScript execution. Use when the user needs to debug API servers, workers, or backend scripts.

## When to Use

This skill activates when:
- User asks to debug Node.js backend or API
- User wants to trace function calls in a running server
- User needs to inspect variables or state in a Node process
- User mentions backend errors, API bugs, or server-side issues
- User wants to run JavaScript in a connected Node process

## Prerequisites

- Use MCP with `PLATFORM=node` or run `node-devtools-mcp` separately
- Connect to the target process before other debug commands (`debug_connect`)

## Capabilities

### Connection
- Connect by PID (`debug_connect` with `pid`)
- Connect by process name (`debug_connect` with `processName`)
- Connect by Docker container (`debug_connect` with `containerName` or `containerId`)
- Connect by inspector port or WebSocket URL

For Docker: use `host.docker.internal` or container name when MCP runs in a container. Mount `/var/run/docker.sock` in the MCP container.

### Non-Blocking Debugging
- **Tracepoints** (`debug_put-tracepoint`): Capture call stack and local variables at code locations
- **Logpoints** (`debug_put-logpoint`): Evaluate and log expressions
- **Exceptionpoints** (`debug_put-exceptionpoint`): Capture on uncaught or all exceptions
- **Watch expressions** (`debug_add-watch`): Evaluate at every tracepoint hit

### Snapshot Retrieval
- `debug_get-probe-snapshots` (types: tracepoint, logpoint, exceptionpoint; returns tracepointSnapshots, logpointSnapshots, exceptionpointSnapshots)
- `debug_clear-probe-snapshots` — clear when done to free memory

### Console & Source Maps
- **Console logs** (`debug_get-logs`): Captures console.log, error, warn from the Node process
- **Source maps** (`debug_resolve-source-location`): Resolve bundled code to original source

### JavaScript Execution
- Use **execute** on the Node platform for batch tool calls (callTool only; no `page`). See [commands/node/execute.md](../../commands/node/execute.md).

## Debugging Workflow

1. **Connect**: `debug_connect` with pid, processName, or containerName
2. **Set probes**: Tracepoints on route handlers, exceptionpoints for errors
3. **Trigger**: Make API requests or trigger the code path
4. **Collect**: `debug_get-probe-snapshots` (types: tracepoint, exceptionpoint)
5. **Investigate**: Use **execute** on Node platform for dynamic inspection (callTool; no `page` binding)
6. **Cleanup**: `debug_clear-probes`, `debug_disconnect`

## Best Practices

- Use `urlPattern` matching script paths (e.g. `routes/api.ts`, `server.js`)
- Start with exceptionpoints to catch errors first
- Use logpoints for lightweight monitoring
- Poll snapshots with `fromSequence` for incremental retrieval
- Clear probes when done to avoid overhead