Debugging and Error Resolution with AI

The 500 Error That Made No Sense

In the previous lesson, we explored code generation that actually works. Now let’s build on that foundation. Last month, a developer spent six hours on a bug. The API returned 500 errors, but only on Tuesdays. Only for users in the EU. Only when they uploaded PDFs larger than 2MB.

He finally pasted the full request flow into Claude and asked: “Why would this only fail on Tuesdays for EU users with large PDFs?”

The answer came in 30 seconds: the EU region’s load balancer had a different timeout configuration, and the PDF processing service had a cron job that ran every Tuesday that consumed extra memory, pushing large file processing over the timeout threshold.

Six hours of detective work, or 30 seconds with the right context. That’s what this lesson teaches you.

The Debugging Trifecta

Every effective AI debugging session needs three things:

1. The error (what went wrong)

TypeError: Cannot read properties of undefined (reading 'map')
at UserList.render (UserList.tsx:24)
at renderWithHooks (react-dom.development.js:14985)

2. The code (where it went wrong)

const UserList = ({ users }: Props) => {
  return (
    <ul>
      {users.map(user => (  // Line 24
        <li key={user.id}>{user.name}</li>
      ))}
    </ul>
  );
};

3. The expectation (what should have happened)

Expected: Render a list of users from the API response
Actual: Crashes with TypeError when the component first mounts

Miss any one of these, and the AI has to guess. Include all three, and it’ll nail the diagnosis almost every time.

For our example, the AI would immediately tell you: users is undefined on first render because the API call hasn’t completed yet. Either add a loading state or default users to an empty array.

Five Debugging Patterns That Work

Pattern 1: Stack Trace Analysis

Paste the full stack trace and ask for a diagnosis.

Here's a stack trace from our production Node.js service.
The error happens intermittently, roughly 5% of requests.

[full stack trace]

Relevant code files:
[paste the files mentioned in the stack trace]

What's causing this, and why is it intermittent?

The AI can trace the execution path, identify the failing line, and reason about intermittent causes (race conditions, resource exhaustion, external service timeouts).

Pattern 2: The “What Changed?” Debug

Something that worked yesterday is broken today. This is where AI shines at diff analysis.

This endpoint worked yesterday and is failing today with
a 422 Validation Error. Here's the git diff of everything
that changed since yesterday:

[paste git diff]

And here's the error:
[paste error]

What in this diff could cause this validation error?

The AI will scan the diff for changes to validation schemas, type definitions, middleware, or configuration that could trigger the error.

Pattern 3: The Rubber Duck Upgrade

The classic rubber duck technique—explaining your problem out loud—works even better with AI. Write out your problem as if explaining to a colleague:

I'm trying to understand why our WebSocket connections
drop after exactly 60 seconds of inactivity.

Here's what I know:
- The WebSocket server has a 120-second timeout configured
- Nginx sits in front of it
- The client sends a ping every 30 seconds
- But connections still drop at the 60-second mark

Here's my Nginx config:
[paste config]

And the WebSocket server config:
[paste config]

What am I missing?

Often, just writing this out will make the answer click. But when it doesn’t, the AI will probably spot that your Nginx proxy_read_timeout is set to 60 seconds, overriding the WebSocket server’s timeout.

Pattern 4: Reproduce-Then-Fix

When you can’t reproduce a bug, describe the symptoms and ask AI to help create a reproduction:

Users report that sorting the data table by the "date"
column sometimes shows incorrect order. I can't reproduce
it locally.

User reports:
- Happens with dates across different years
- Some users see it, others don't
- Clearing cache doesn't help

Here's the sorting code:
[paste sorting implementation]

What could cause inconsistent sorting, and how can I
create a test case that reproduces it?

The AI might identify that you’re sorting date strings lexicographically instead of chronologically, and that the issue only appears when dates cross year boundaries (e.g., “12/31/2025” vs “01/01/2026”).

Pattern 5: Error Message Translation

Some error messages are genuinely cryptic. AI excels at translating them:

I'm getting this error and I have no idea what it means:

FATAL ERROR: Ineffective mark-compacts near heap limit
Allocation failed - JavaScript heap out of memory

This happens during our build process when processing
more than 500 markdown files. Here's our build script:
[paste build config]

The AI translates: your Node.js process is running out of memory during the build. It’ll suggest increasing the Node.js heap size with --max-old-space-size and probably identify which part of your build is memory-hungry.

Quick Check: Debug This

Here’s a real debugging scenario. What would you paste into an AI assistant?

The bug: Your React app’s search feature returns results, but clicking a result navigates to the wrong page.

What you know: It only happens when the search results contain items with special characters in their names (like “Ben & Jerry’s”).

Think about what code you’d include and what context would help. The key files would be: the search results component, the URL construction logic, and the navigation handler. The likely cause? URL encoding—the & is being interpreted as a query parameter separator.

Advanced: Multi-File Debugging

Real bugs rarely live in a single file. When the issue spans multiple files, here’s how to structure your AI request:

I have a bug where user preferences don't persist after
page reload. The save appears to work (no errors), but
the preferences reset on refresh.

Here's the flow:
1. User updates preferences in SettingsPanel.tsx
2. Which calls PreferenceService.save()
3. Which calls the API endpoint in preferences.controller.ts
4. Which writes to the database via PreferenceRepository.ts

[paste each file's relevant code]

The API returns 200 with the updated preferences.
Browser DevTools shows the request succeeds.
But after reload, old preferences come back.

Where in this chain is the data getting lost?

By showing the complete flow, the AI can trace the data through each layer. Maybe the API saves correctly but the frontend is reading from a stale cache. Maybe the database write succeeds but the read query hits a replica that hasn’t synced yet.

When AI Gets Debugging Wrong

AI debugging isn’t perfect. Watch out for these traps:

The confident wrong answer. AI will sometimes give a plausible-sounding explanation that’s completely wrong. Always verify by checking the actual behavior against the AI’s explanation.

Suggesting symptoms, not causes. Sometimes AI fixes the error message without addressing the root cause. If the fix is “add a null check,” ask: “But why is this value null in the first place?”

Ignoring your environment. AI might suggest fixes for a different version of a library or a different OS. Always mention your specific versions.

Over-complicated solutions. If the AI suggests a 50-line fix for what should be a simple bug, step back. Ask: “Is there a simpler explanation for this error?”

Building Your Debugging Prompt Template

Here’s a template you can reuse for any debugging session:

## Error
[paste error message and stack trace]

## Environment
- Language/Runtime: [e.g., Node.js 20.x, Python 3.12]
- Framework: [e.g., Express 4.18, Django 5.0]
- OS: [if relevant]
- Relevant dependencies: [versions of key libraries]

## Code
[paste relevant code files/functions]

## Expected Behavior
[what should happen]

## Actual Behavior
[what actually happens]

## What I've Already Tried
[list any debugging steps taken]

## Additional Context
[any patterns: intermittent? specific conditions?]

Fill this in before your next debugging session. You’ll be amazed at how fast AI solves it when given proper context.

Key Takeaways

• Always provide the debugging trifecta: error, code, and expected behavior
• Use the right debugging pattern for the situation (stack trace analysis, diff debugging, rubber duck, reproduction, or error translation)
• For multi-file bugs, show the complete data flow
• Verify AI’s explanations—don’t just apply fixes blindly
• Ask “why?” to get to root causes, not just symptom fixes
• Build a reusable debugging prompt template

Next up: testing. Now that you can generate and debug code, let’s make sure it stays working with AI-generated test suites that cover cases you’d never think of on your own.

Up next: In the next lesson, we’ll dive into Testing and Quality Assurance.