# Debugging

> Debug web and Node.js applications using console inspection, network analysis, and non-blocking code debugging. Use when the user reports bugs, wants to debug JavaScript (browser or backend), inspect network requests, troubleshoot page/API issues, trace function calls, or monitor exceptions.

- Skill: `serkan-ozal/debugging` (Agent Skill)
- Install (CLI): `npx skillmds@latest add serkan-ozal/debugging`
- Raw SKILL.md: https://api.skillmd.com/api/skills/serkan-ozal/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/debugging

---


# Debugging Skill

Debug web applications and Node.js backends using console inspection, network analysis, and non-blocking code debugging with tracepoints, logpoints, and exception monitoring.

## When to Use

This skill activates when:
- User reports a bug or error on a web page or backend
- User asks to debug JavaScript (frontend or Node.js)
- User wants to inspect API calls or network requests
- User needs to troubleshoot page loading or API handler issues
- User mentions console errors or warnings
- User wants to debug without breakpoints
- User needs to trace function calls or monitor variables

## Capabilities

### Console Inspection
```bash
browser-devtools-cli o11y get-console-messages
browser-devtools-cli o11y get-console-messages --type warning
browser-devtools-cli --json o11y get-console-messages --type error
```

### Network Analysis
```bash
browser-devtools-cli o11y get-http-requests
browser-devtools-cli --json o11y get-http-requests --resource-type fetch
browser-devtools-cli --json o11y get-http-requests --status '{"min":400}'
```

### Tracepoints (Non-Blocking)
```bash
browser-devtools-cli debug put-tracepoint --url-pattern "app.js" --line-number 42
browser-devtools-cli debug list-probes --types tracepoint
browser-devtools-cli debug remove-probe --type tracepoint --id <probe-id>
browser-devtools-cli debug clear-probes --types tracepoint
```

### Logpoints
```bash
browser-devtools-cli debug put-logpoint --url-pattern "app.js" --line-number 50 --log-expression "user.id"
browser-devtools-cli debug list-probes --types logpoint
browser-devtools-cli debug remove-probe --type logpoint --id <probe-id>
browser-devtools-cli debug clear-probes --types logpoint
```

### Exception Monitoring
```bash
browser-devtools-cli debug put-exceptionpoint --state uncaught
browser-devtools-cli debug put-exceptionpoint --state all
```

### Watch Expressions
```bash
browser-devtools-cli debug add-watch --expression "this"
browser-devtools-cli debug add-watch --expression "user.id"
browser-devtools-cli debug list-probes --types watch
browser-devtools-cli debug remove-probe --type watch --id <probe-id>
browser-devtools-cli debug clear-probes --types watches
```

### Retrieve and Clear Snapshots (Unified)
```bash
browser-devtools-cli --json debug get-probe-snapshots
browser-devtools-cli --json debug get-probe-snapshots --types tracepoint,logpoint,exceptionpoint
browser-devtools-cli --json debug get-probe-snapshots --probe-id "tp_abc" --from-sequence 0
browser-devtools-cli debug clear-probe-snapshots
browser-devtools-cli debug clear-probe-snapshots --types tracepoint --probe-id "tp_abc"
```

### Node.js Backend Debugging (node-devtools-cli)

For debugging Node.js API servers, backends, or scripts:

```bash
# 1. Connect to process (by PID, name, or Docker)
node-devtools-cli --session-id backend-debug debug connect --pid 12345
node-devtools-cli --session-id backend-debug debug connect --process-name "server.js"

# 2. Tracepoint on route handler or service
node-devtools-cli --session-id backend-debug debug put-tracepoint \
  --url-pattern "routes/api.ts" \
  --line-number 42

# 3. Exception monitoring
node-devtools-cli --session-id backend-debug debug put-exceptionpoint --state uncaught

# 4. Console logs from Node process
node-devtools-cli --session-id backend-debug --json debug get-logs
node-devtools-cli --session-id backend-debug --json debug get-logs --search "error"

# 5. Retrieve snapshots (after triggering the code path)
node-devtools-cli --session-id backend-debug --json debug get-probe-snapshots
node-devtools-cli --session-id backend-debug --json debug get-probe-snapshots --types tracepoint,exceptionpoint

# 6. Status and cleanup
node-devtools-cli --session-id backend-debug debug status
node-devtools-cli debug disconnect
```

`urlPattern` in Node context matches **script file paths** (e.g., `server.js`, `routes/users.ts`). See [node-devtools-cli](../node-devtools-cli/SKILL.md) skill for full reference.

### Error Investigation
```bash
browser-devtools-cli content take-screenshot --name "error-state"
browser-devtools-cli content get-as-html --selector ".error-container"
```

## Basic Debugging Workflow

1. **Reproduce**: Navigate to the problematic page
2. **Capture**: Take screenshot of current state
3. **Inspect Console**: Check for JavaScript errors
4. **Analyze Network**: Look for failed requests
5. **Investigate**: Run diagnostic JavaScript
6. **Document**: Summarize findings with evidence

```bash
# Quick debug workflow
browser-devtools-cli navigation go-to --url "https://example.com"
browser-devtools-cli content take-screenshot --name "initial"
browser-devtools-cli --json o11y get-console-messages --type warning
browser-devtools-cli --json o11y get-http-requests --status '{"min":400}'
```

## Advanced Debugging Workflow (Non-Blocking)

### 1. Set Up Probes

```bash
SESSION="--session-id debug-session"

# Navigate to app
browser-devtools-cli $SESSION navigation go-to --url "http://localhost:3000"

# Tracepoint on a function
browser-devtools-cli $SESSION debug put-tracepoint \
  --url-pattern "app.js" \
  --line-number 42

# Exception monitoring
browser-devtools-cli $SESSION debug put-exceptionpoint --state uncaught
```

### 2. Add Watch Expressions

```bash
browser-devtools-cli $SESSION debug add-watch --expression "this"
browser-devtools-cli $SESSION debug add-watch --expression "user.id"
```

### 3. Interact with Application

```bash
browser-devtools-cli $SESSION interaction click --selector "#submit-btn"
browser-devtools-cli $SESSION sync wait-for-network-idle
```

### 4. Retrieve Snapshots

```bash
browser-devtools-cli $SESSION --json debug get-probe-snapshots
browser-devtools-cli $SESSION --json debug get-probe-snapshots --types tracepoint,exceptionpoint
browser-devtools-cli $SESSION --json debug get-probe-snapshots --from-sequence 0
```

### 5. Clean Up

```bash
browser-devtools-cli $SESSION debug clear-probes
browser-devtools-cli $SESSION debug clear-probe-snapshots
browser-devtools-cli session delete debug-session
```

## Probe Types Summary

| Probe | Purpose | Output | CLI |
|-------|---------|--------|-----|
| Tracepoint | Function calls | Stack, locals, watches | browser-devtools-cli, node-devtools-cli |
| Logpoint | Expression values | Evaluated result | both |
| Exceptionpoint | Error catching | Error, stack trace | both |
| Watch | Per-tracepoint expressions | watchResults in snapshot | list/remove via list-probes, remove-probe, clear-probes |

## Best Practices

1. **Choose the right CLI**: Use `browser-devtools-cli` for frontend/page debugging; use `node-devtools-cli` for Node.js backend/API debugging
2. **Always check console for errors first**
3. **Filter network requests** to relevant endpoints
4. **Take screenshots** before and after actions (browser)
5. **Use source maps** for minified/bundled code
6. **Start with exceptions** to catch errors first
7. **Use logpoints** for lightweight monitoring
8. **Poll snapshots** with `--from-sequence` for efficiency
9. **Clear probes** when done to avoid overhead
10. **Document reproduction steps** clearly