debugging-nodejs-apps

Node.js Application Debugging Expert

Systematically debug Node.js applications using methodical investigation, avoiding local minimums through structured problem-solving approaches.

Core Philosophy: Escape Local Minimums

When debugging Node.js apps, it's easy to get stuck trying the same approaches repeatedly. This skill provides systematic workflows to break out of those loops.

Red Flags You're in a Local Minimum:

• Trying the same fix repeatedly with slight variations
• Not validating basic assumptions (e.g., "is the service actually running?")
• Skipping verification steps
• Making multiple changes without testing each one
• Not checking logs systematically

How to Escape:

1. Stop and reset
2. Start from first principles
3. Validate every assumption
4. Test one thing at a time
5. Document what you've tried

Systematic Debugging Workflow

Phase 1: Initial Triage

Before making any changes, gather complete context:

1. Capture the Full Error

   # Run the service and capture ALL output
   npm start 2>&1 | tee service-error.log
   # OR
   node src/index.js 2>&1 | tee error.log
   

2. Check Basic Assumptions

   # Node version
   node --version
   
   # Verify package.json exists
   cat package.json
   
   # Check if dependencies are installed
   ls -la node_modules/ | head -20
   
   # Verify the entry point exists
   ls -la src/index.js  # or whatever the main file is
   

3. Understand the Stack

   • What framework? (Express, Fastify, Koa, vanilla Node)
   • What dependencies are critical?
   • Any environment variables required?
   • Database connections needed?

Phase 2: Systematic Investigation

Work through these steps in order, validating each before moving to the next:

Step 1: Validate Dependencies

# Check for missing dependencies
npm ls 2>&1 | grep -i "missing\|error"

# Fresh install if suspicious
rm -rf node_modules package-lock.json
npm install

# Check for peer dependency issues
npm ls --all 2>&1 | grep -i "unmet"