Troubleshooting Guide

Emergency procedures when stuck, tests failing, or errors occurring. Use after 30+ minutes stuck on same issue.

Emergency Procedures

When Stuck (>30 min on one issue)

STOP IMMEDIATELY - Don't keep trying random solutions

Follow this process:

•
Document What You've Tried
- •List all approaches attempted
- •Note exact error messages
- •Record what changed between working and broken states
•
Simplify & Isolate
- •Can you reproduce in isolation? (minimal test case)
- •Remove complexity: Comment out code until error disappears
- •Bisect: Is it old code or new code causing the issue?
•
Check Fundamentals
- • Are dependencies installed and up to date?
- • Is configuration correct? (environment variables, paths)
- • Are file permissions correct?
- • Is the right version running? (restart server, clear cache)
•
Search for Similar Issues
- •Google exact error message
- •Check GitHub issues for dependencies
- •Search Stack Overflow
- •Review .claude/memory/ for similar past problems
•
Ask for Help
- •
  Present clear problem statement to user:
  - •What are you trying to do?
  - •What happens instead?
  - •What have you tried?
  - •What's the exact error?
•
Record the Solution
- •Once resolved, create .claude/memory/YYYY-MM-DD-issue-name.md
- •Document: Problem, Root Cause, Solution, Prevention

When Tests Break Unexpectedly

Diagnosis Steps

•

Identify When It Broke

bash

# Check recent changes
git diff HEAD~1

# Run tests on last commit
git checkout HEAD~1
npm test  # or cargo test, pytest, go test

•

Isolate the Failing Test

bash

# Run single test file
npm test path/to/test.spec.ts

# Run single test case
npm test -t "specific test name"

•
Check for Flakiness
- •Run test 10 times: Does it fail consistently?
- •Is it timing-dependent? (race condition)
- •Does order matter? (test interdependence)

Recovery Process

If tests broke after your change:

bash

# Option 1: Revert and re-apply incrementally
git reset --hard HEAD~1
# Re-apply changes one file at a time, testing after each

# Option 2: Git bisect (find exact breaking commit)
git bisect start
git bisect bad HEAD
git bisect good <last-known-good-commit>
# Git will checkout commits; run tests and mark good/bad

If tests broke without your changes:

•Check dependency updates (package-lock.json, Cargo.lock changes)
•Check environment differences (Node version, Python version)
•Check for flaky tests (run 10 times to confirm)

When Security Issue Found

PRIORITY: CRITICAL

Immediate Actions

•
DO NOT COMMIT vulnerable code
bash
```
# Stash changes if needed
git stash
```
•
Fix Immediately
- •Security takes priority over all other work
- •Apply fix from guardrails or security best practices
•
Add Regression Test
- •Ensure vulnerability can't be reintroduced
- •Test both the exploit and the fix
•
Document in Memory
- •Create .claude/memory/YYYY-MM-DD-security-fix-NAME.md
- •Document: Vulnerability, Impact, Fix, Prevention
•
Review Similar Code
- •Search codebase for same pattern
- •Fix all instances (not just the one found)

Common Security Issues & Fixes

SQL Injection:

javascript

// ❌ Vulnerable
db.query(`SELECT * FROM users WHERE id = ${userId}`);

// ✅ Fixed
db.query('SELECT * FROM users WHERE id = ?', [userId]);

XSS (Cross-Site Scripting):

javascript

// ❌ Vulnerable
element.innerHTML = userInput;

// ✅ Fixed
element.textContent = userInput;
// Or use framework escaping (React auto-escapes)

Hardcoded Secrets:

javascript

// ❌ Vulnerable
const API_KEY = "sk_live_abc123";

// ✅ Fixed
const API_KEY = process.env.API_KEY;

When Performance Degrades

Diagnosis

•
Measure First
- •Don't guess - profile the code
- •Use browser DevTools (frontend)
- •Use profilers (cargo flamegraph, py-spy, pprof)

•

Identify Bottleneck

bash

# Node.js
node --prof app.js
node --prof-process isolate-*.log

# Python
python -m cProfile -o output.prof script.py
python -m pstats output.prof

# Go
go test -bench . -cpuprofile=cpu.prof
go tool pprof cpu.prof

•
Common Culprits
- • N+1 database queries (use eager loading)
- • Large data loaded into memory (use pagination/streaming)
- • Inefficient algorithms (O(n²) when O(n) possible)
- • Missing indexes on database columns
- • Unnecessary re-renders (React, Vue)
- • Blocking I/O in async contexts

Fix Priorities

•Big wins first: Fix O(n²) → O(n), add database indexes
•Measure improvement: Benchmark before/after
•Don't over-optimize: 80% of time spent in 20% of code

When Build Fails

Common Issues

Dependency Conflicts:

bash

# Node.js
rm -rf node_modules package-lock.json
npm install

# Python
pip install --upgrade pip
pip install -r requirements.txt --force-reinstall

# Go
go clean -modcache
go mod tidy
go mod download

# Rust
cargo clean
cargo build

Version Mismatch:

•Check Node/Python/Go/Rust version matches project requirements
•Use version managers: nvm, pyenv, gvm, rustup

Missing Environment Variables:

bash

# Check .env.example vs .env
diff .env.example .env

# Set required variables
export DATABASE_URL="..."
export API_KEY="..."

When Git Issues Occur

Merge Conflicts

bash

# Show conflicted files
git status

# Open files, look for conflict markers:
<<<<<<< HEAD
Your changes
=======
Their changes
>>>>>>> branch-name

# Resolve manually, then:
git add <resolved-files>
git commit

Accidentally Committed Secrets

CRITICAL - Act immediately:

bash

# Remove from last commit (if not pushed)
git reset HEAD~1
# Remove secret from file
# Add file to .gitignore
git add .
git commit -m "Remove secrets"

# If already pushed - rotate the secret immediately
# Then use BFG Repo-Cleaner or git-filter-branch

Lost Work

bash

# Find lost commits
git reflog

# Recover lost commit
git checkout <commit-hash>

# Create branch from recovered commit
git checkout -b recovery-branch

Red Flags (Stop & Reassess)

Stop immediately if you encounter these:

Code Red Flags

•❌ Same error after 3 different attempted fixes
•❌ Solution getting more complex instead of simpler
•❌ Not understanding why a fix works ("it just works now")
•❌ Touching >10 files for a "simple" bug fix
•❌ Breaking existing tests to make new code work

Process Red Flags

•❌ Skipping tests because "I'll add them later"
•❌ Committing commented-out code "just in case"
•❌ Ignoring linter errors "they're not important"
•❌ Using any or unsafe to "make TypeScript/Rust happy"
•❌ Copying code without understanding it

When you see red flags:

•STOP adding more code
•Revert to last working state
•Apply COMPLEX mode: Full 4D decomposition
•Ask user for guidance if still stuck

Common Error Messages & Solutions

TypeScript/JavaScript

"Cannot find module"

bash

npm install
# or
npm install <package-name>

"Type 'X' is not assignable to type 'Y'"

•Check type definitions: Are they correct?
•Use type assertions only if you're certain: as Y
•Consider using unknown and narrowing

"Module not found" (frontend)

•Check import paths (case-sensitive)
•Restart dev server
•Clear build cache

Python

"ModuleNotFoundError"

bash

pip install -r requirements.txt
# Or
pip install <module-name>

"IndentationError"

•Use consistent indentation (spaces vs tabs)
•Configure editor to use 4 spaces

"AttributeError: ... has no attribute ..."

•Check object type (use type() or debugger)
•Check if attribute exists (hasattr())

Go

"cannot find package"

bash

go mod tidy
go mod download

"undefined: ..."

•Check imports
•Check if function/variable is exported (capitalized)

Rust

"cannot borrow x as mutable"

•Only one mutable borrow allowed
•Consider refactoring to avoid simultaneous borrows

"use of moved value"

•Value was moved (ownership transferred)
•Clone if needed, or use borrowing (&)

Recovery Checklist

After resolving any major issue:

• Tests passing
• Guardrails validated
• Root cause understood (not just symptom fixed)
• Documented in .claude/memory/ if significant
• Similar code reviewed for same issue
• Prevention added (test, linter rule, guardrail)

Remember: Being stuck is normal. Following a systematic process beats random attempts. Document your solutions - future you will thank you!