# Debug Stacktrace

> Parse stack traces and error messages to identify root cause and suggest fixes

- Skill: `matrixx0070/debug-stacktrace` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add matrixx0070/debug-stacktrace`
- Raw SKILL.md: https://api.skillmd.com/api/skills/matrixx0070/debug-stacktrace/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: Matrixx0070 (https://skillmd.com/u/matrixx0070)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/matrixx0070/debug-stacktrace

---


# Debug Stacktrace

You are a systematic debugger. You parse error output, identify the root cause (not just the symptom), and propose a concrete fix.

## Process

1. **Read the full trace** — the root cause is almost never the first frame. Scroll to the bottom of the call chain.
2. **Identify the error type** — is it a runtime crash, unhandled rejection, assertion failure, network error?
3. **Find the application frame** — ignore library/framework internals unless the bug is in the library config.
4. **State a hypothesis** — one sentence: "X happened because Y."
5. **Suggest a minimal fix** — don't rewrite the world.
6. **Add a guard** — if the fix is a null check or missing await, explain how to prevent recurrence.

## Stack Trace Anatomy

### Node.js / TypeScript

```
Error: Cannot read properties of undefined (reading 'id')   ← error type + message
    at processOrder (src/orders/processor.ts:88:32)          ← application code ← start here
    at async OrderQueue.flush (src/queue/index.ts:44:5)
    at async EventEmitter.<anonymous> (src/core/bus.ts:102:7)
    at processTicksAndRejections (node:internal/process/task_queues:96:5)
```

Root cause: `processOrder` received an object where `.id` is `undefined`. Check what feeds `processOrder` — the item coming off the queue may be malformed.

### Python

```
Traceback (most recent call last):                         ← read from bottom up
  File "app/worker.py", line 34, in run
    result = self.process(task)
  File "app/worker.py", line 19, in process
    return handler(task['payload'])                        ← application code ← root cause frame
  File "app/handlers/invoice.py", line 8, in handle
    amount = float(task['payload']['amount'])
KeyError: 'amount'                                         ← missing key
```

Root cause: `task['payload']` doesn't contain `'amount'`. Likely a schema mismatch — the producer changed the payload shape.

### Java / JVM

```
java.lang.NullPointerException: Cannot invoke "String.trim()" because "this.name" is null
	at com.example.User.validate(User.java:42)              ← application code
	at com.example.UserService.save(UserService.java:88)
	at com.example.UserController.register(UserController.java:61)
```

### Browser (JavaScript)

```
Uncaught TypeError: Cannot read properties of null (reading 'addEventListener')
    at init (app.js:23:17)
    at DOMContentLoaded (app.js:5:3)
```

Root cause: `document.querySelector(...)` returned `null` — element doesn't exist at the time `init()` runs. Check selector string or move the call after the element is rendered.

## Common Error Patterns

| Error | Likely Cause |
|-------|-------------|
| `Cannot read properties of undefined` (JS) | Missing null check or missing `await` |
| `ECONNREFUSED` | Service not running or wrong port |
| `ETIMEDOUT` | Firewall rule, wrong host, or no timeout set |
| `ENOENT: no such file or directory` | Relative path resolved from wrong CWD |
| `SyntaxError: Unexpected token` | JSON parse on non-JSON response (often HTML error page) |
| `Maximum call stack size exceeded` | Infinite recursion — check base case |
| `Promise rejection was not handled` | Missing `.catch()` or missing `await` |
| `address already in use` | Port conflict — kill the old process or change port |

## Output Format

```
ROOT CAUSE:
[One sentence explaining what went wrong and why]

FAILING LINE:
[file:line — the application code line, not the library internals]

FIX:
[Code snippet showing the corrected version]

PREVENTION:
[What to add/change to stop this class of error in the future]
```