Madappgang Claude Code Debugging Strategies

Error Analysis

Stack Trace Reading

Read stack traces bottom to top:

Error: Cannot read property 'name' of undefined
    at formatUser (src/utils/format.ts:42)      ← Error thrown here
    at processUsers (src/services/user.ts:28)    ← Called from here
    at UserList.render (src/components/UserList.tsx:15)
    at App.render (src/App.tsx:8)                ← Entry point

Focus on YOUR code - skip framework/library internals initially.

Error Categories

Debugging Techniques

Binary Search (Bisection)

When the bug is somewhere in a large codebase:

1. Find a known good state (commit, version)
2. Find current bad state
3. Test the midpoint
4. Narrow to half with bug
5. Repeat until found

Git bisect:

git bisect start
git bisect bad                    # Current commit is broken
git bisect good v1.0.0           # v1.0.0 was working
# Git checks out midpoint, test it
git bisect good/bad              # Mark and continue

Wolf Fence Algorithm

Split the code into sections and determine which section contains the bug:

┌─────────────────────────────────────┐
│           Code Section A            │ ← Test: Bug here?
├─────────────────────────────────────┤
│           Code Section B            │ ← Test: Bug here?
├─────────────────────────────────────┤
│           Code Section C            │ ← Test: Bug here?
└─────────────────────────────────────┘

Add logging/breakpoints at section boundaries, narrow down.

Rubber Duck Debugging

Explain the code line by line (to a rubber duck, colleague, or yourself):

1. Explain what the code SHOULD do
2. Explain what it ACTUALLY does
3. The discrepancy reveals the bug

Change One Thing at a Time

When experimenting:

• Make ONE change
• Test
• Observe result
• Revert if no improvement
• Repeat

Data Flow Tracing

Backwards Tracing

Start at the error, trace backwards:

1. Error occurs at line 42: user.name is undefined
2. Where does `user` come from? Line 38: const user = getUser(id)
3. What does getUser return? Check function...
4. getUser queries database, returns undefined if not found
5. Root cause: No null check after getUser

Forward Tracing

Start at input, trace forward:

1. User enters email: "test@example"
2. Form submits to /api/register
3. API validates email... passes (bug: missing TLD check)
4. Saves to database with invalid email
5. Later processes fail on invalid email

Logging Strategies

Strategic Log Placement

function processOrder(order) {
  console.log("processOrder START", { orderId: order.id });

  try {
    const validated = validateOrder(order);
    console.log("Validation passed", { orderId: order.id });

    const result = saveOrder(validated);
    console.log("processOrder SUCCESS", { orderId: order.id, result });

    return result;
  } catch (error) {
    console.error("processOrder FAILED", {
      orderId: order.id,
      error: error.message,
      stack: error.stack,
    });
    throw error;
  }
}

Log Levels

Structured Logging

// BAD: Unstructured
console.log("User " + userId + " ordered " + items.length + " items");

// GOOD: Structured
logger.info("Order placed", {
  userId,
  itemCount: items.length,
  total: order.total,
  timestamp: new Date().toISOString(),
});

Breakpoint Strategies

Types of Breakpoints

Effective Breakpoint Placement

1. Before the error - See state leading to failure
2. At decision points - Check which branch executes
3. At data boundaries - API calls, DB queries
4. In loops - Check iteration values

Common Bug Patterns

Off-by-One Errors

// BUG: Index out of bounds
for (let i = 0; i <= array.length; i++) {
  console.log(array[i]); // Fails on last iteration
}

// FIX
for (let i = 0; i < array.length; i++) {
  console.log(array[i]);
}

Race Conditions

// BUG: Race condition
async function getData() {
  fetchData().then((data) => {
    this.data = data;
  });
  processData(this.data); // May run before fetch completes!
}

// FIX: Await the result
async function getData() {
  this.data = await fetchData();
  processData(this.data);
}

Null Reference

// BUG: Accessing property of undefined
const name = user.profile.name;

// FIX: Optional chaining or guard
const name = user?.profile?.name;
// or
if (user && user.profile) {
  const name = user.profile.name;
}

State Mutation

// BUG: Mutating input
function addTax(price) {
  price.total = price.amount * 1.2; // Mutates input!
  return price;
}

// FIX: Return new object
function addTax(price) {
  return {
    ...price,
    total: price.amount * 1.2,
  };
}

Closure Pitfalls

// BUG: All callbacks share same i
for (var i = 0; i < 3; i++) {
  setTimeout(() => console.log(i), 100); // Logs: 3, 3, 3
}

// FIX: Use let (block scope) or capture value
for (let i = 0; i < 3; i++) {
  setTimeout(() => console.log(i), 100); // Logs: 0, 1, 2
}

Environment-Specific Debugging

Browser (JavaScript)

• DevTools Console
• Network tab for API calls
• Elements tab for DOM
• Sources tab for breakpoints
• Performance tab for bottlenecks
• Application tab for storage

Node.js

# Start with inspector
node --inspect app.js

# Break on first line
node --inspect-brk app.js

Backend APIs

• Request/response logging
• Database query logging
• Trace IDs for distributed tracing
• Health check endpoints

Debugging Checklist

When stuck, verify:

• Input: Is input data correct?
• Config: Are environment variables set?
• Dependencies: Are all services running?
• Versions: Is the correct version deployed?
• Cache: Is stale data being used?
• Permissions: Does the code have required access?
• Timing: Are async operations completing?
• State: Is application state as expected?

Prevention

Defensive Coding

function processUser(user) {
  // Guard clauses
  if (!user) throw new Error("User is required");
  if (!user.email) throw new Error("User email is required");

  // Type assertions (TypeScript)
  const email = user.email as string;

  // Proceed with validated data
  return formatUser(user);
}

Assertions

// Development-time checks
function divide(a, b) {
  console.assert(b !== 0, "Division by zero");
  return a / b;
}

Error Boundaries

try {
  riskyOperation();
} catch (error) {
  // Log with context
  logger.error("Operation failed", {
    error: error.message,
    stack: error.stack,
    context: { userId, operation: "riskyOperation" },
  });

  // Recover or rethrow
  throw new OperationError("Failed to complete operation", { cause: error });
}

Debugging strategies applicable to all technology stacks