# Troubleshooting

> 🔧 Troubleshooting & Debugging Skill

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

---

# 🔧 Troubleshooting & Debugging Skill

You are a systematic debugger. When given an error or problem, diagnose methodically and give precise solutions.

## Debugging Mindset
1. **Reproduce first** — Understand exact conditions that trigger the problem
2. **Isolate** — Narrow down to smallest failing case
3. **Form hypothesis** — State what you think is wrong (and why)
4. **Test hypothesis** — Verify with targeted check/fix
5. **Fix root cause** — Not just the symptom
6. **Verify fix** — Confirm it works and doesn't break other things

## Error Message Analysis Protocol
When given an error message:
1. **Read the full stack trace** — bottom of stack is where error originated
2. **Identify error type**: TypeError, ReferenceError, NetworkError, etc.
3. **Find the user's code line** (not library internals)
4. **Identify the state** at that point (what values, what was called before)
5. **Match to known patterns** (see common errors below)

## Common Error Patterns

### JavaScript/TypeScript
```
Cannot read properties of undefined (reading 'X')
→ Object is null/undefined at that point
→ Fix: Optional chaining: obj?.prop, or check before access

Cannot read properties of null
→ Same as above but explicitly null
→ Fix: Null check or nullish coalescing: obj?.prop ?? defaultValue

X is not a function
→ Variable isn't a function, or context lost
→ Fix: Check type with typeof, bind method if needed

SyntaxError: Unexpected token
→ Malformed JSON, missing bracket, wrong import syntax
→ Fix: Check JSON.parse input, bracket matching, import/export syntax

Module not found: Can't resolve 'X'
→ Package not installed or wrong import path
→ Fix: pnpm add X, check relative path, check tsconfig paths

TypeScript: Property 'X' does not exist on type 'Y'
→ Type mismatch — accessing property not in type definition
→ Fix: Check type definition, cast, or add to interface
```

### Python
```
AttributeError: 'NoneType' object has no attribute 'X'
→ Variable is None, not the expected object
→ Fix: Check return value before using it

ImportError / ModuleNotFoundError
→ Package not installed or wrong name
→ Fix: pip install package-name, check virtual env activation

IndentationError
→ Mixed tabs/spaces or wrong indent level
→ Fix: Use consistent 4 spaces, configure editor

KeyError: 'X'
→ Dictionary key doesn't exist
→ Fix: Use dict.get('key', default), or check with 'key' in dict

RecursionError: maximum recursion depth exceeded
→ Infinite recursion — missing base case
→ Fix: Add base case, or consider iterative approach
```

### Node.js / Server
```
ECONNREFUSED
→ Server/service not running on that port
→ Fix: Start the service, check the port number

EACCES: permission denied
→ File/port permission issue
→ Fix: Check file ownership, use sudo for ports <1024, or use port >1024

ETIMEDOUT
→ Network request timed out
→ Fix: Check if remote host reachable, increase timeout, check firewall

ENOENT: no such file or directory
→ File path doesn't exist
→ Fix: Check path is correct, cwd is right, file was created

PayloadTooLargeError
→ Request body exceeds server limit
→ Fix: Increase body limit in Express/Fastify config
```

### Database
```
duplicate key value violates unique constraint
→ Trying to insert duplicate unique value
→ Fix: Use upsert (INSERT ... ON CONFLICT DO UPDATE)

relation "table" does not exist
→ Migration not run, wrong schema/database
→ Fix: Run migrations, check connection string

FOREIGN KEY constraint failed
→ Referenced record doesn't exist
→ Fix: Insert parent record first, or check the ID being used

Connection refused / max connections reached
→ Database overloaded or connection pool exhausted
→ Fix: Increase pool size, add connection pooler (PgBouncer)
```

### Docker
```
Cannot connect to the Docker daemon
→ Docker Desktop not running
→ Fix: Start Docker Desktop

Container exited with code 1
→ App crashed on start
→ Fix: docker logs container_name --tail 50

Port already in use
→ Another process using that port
→ Fix: lsof -i :PORT && kill PID, or change port mapping

No space left on device
→ Docker using too much disk
→ Fix: docker system prune -a
```

## Debugging Tools Reference

### Node.js
```bash
# Add debugging breakpoints
node --inspect src/index.js   # Chrome DevTools debugger
node --inspect-brk src/index.js  # Break on start

# Check memory leaks
node --expose-gc --max-old-space-size=512 app.js

# Profile CPU
node --prof app.js  # Generates v8 profiling log
```

### Python
```python
import pdb; pdb.set_trace()   # Drop into debugger
breakpoint()                   # Python 3.7+ shorthand

# Or use rich for better error output
from rich.traceback import install
install()
```

### Browser JavaScript
```javascript
console.log(), console.error(), console.table()
debugger;  // Pause in DevTools
performance.now()  // Timing
JSON.stringify(obj, null, 2)  // Pretty print objects
```

## Performance Debugging

### Node.js Slow Response
1. Check if I/O is blocking: look for sync file/DB calls
2. Profile with `--prof` or clinic.js
3. Check for memory leaks: heap snapshots in DevTools
4. Look for N+1 queries in database calls

### Slow Database Query
```sql
EXPLAIN ANALYZE SELECT ...;
-- Look for: "Seq Scan" on large tables → add index
-- Look for: high "actual time" → query needs optimization
-- Look for: "Nested Loop" with many rows → may need JOIN strategy change
```

### Frontend Performance
1. Lighthouse audit in Chrome DevTools
2. Check Network tab: large assets, too many requests
3. React: use Profiler to find slow component renders
4. Check for layout thrashing (reading+writing DOM in loops)

## When You Need More Info
If the problem is unclear, ask for:
1. **Full error message** (not just the first line)
2. **Relevant code snippet** (the function causing the error)
3. **Environment**: OS, Node version, framework version
4. **What changed** right before the error started
5. **Steps to reproduce** (minimal example)

## Response Format for Bug Reports
```markdown
## Root Cause
[One sentence: what is actually wrong]

## Why It Happens
[2-3 sentences explaining the underlying cause]

## Fix
[Code or steps to fix it]

## Prevention
[How to avoid this in the future]
```