Back to course
Reading What AI Writes
Lesson 5 of 10
Free

When AI Gets It Wrong

Learn how to identify problems, describe what's broken, and guide Claude to fix issues. Debugging is a conversation, not a mystery.

15 min read
Share

Claude built something. You ran it. It didn’t work.

This happens. It’s not a failure—it’s part of the process. The difference between getting stuck and making progress is knowing how to have a debugging conversation.

Why AI Gets Things Wrong

AI makes mistakes for predictable reasons:

  1. Ambiguous instructions — Your request could be interpreted multiple ways
  2. Missing context — AI didn’t know something important about your situation
  3. Assumptions — AI assumed something that isn’t true in your case
  4. Edge cases — The common case works, but your specific case doesn’t

None of these require you to understand programming. They require you to observe and describe.

The Debugging Mindset

When something breaks, you need to answer three questions:

  1. What did I expect to happen?
  2. What actually happened?
  3. What’s the difference?

That’s it. If you can describe those three things, Claude can usually fix the problem.

Types of Problems

The Error Message

The script crashes with an error. You see something like:

FileNotFoundError: [Errno 2] No such file or directory: 'contracts/draft.docx'

What to do: Copy the entire error message and paste it to Claude:

I ran the script and got this error:

FileNotFoundError: [Errno 2] No such file or directory: 'contracts/draft.docx'

What does this mean and how do I fix it?

Error messages usually say exactly what’s wrong—in this case, it can’t find a file called draft.docx in the contracts folder.

The Wrong Result

The script runs without errors, but produces incorrect output:

You: The script said it found 0 confidentiality clauses, but I know the contract has three.

Claude: Let me check how the script is searching. Can you share the exact text of one of the clauses it should have found?

What to do: Describe the expected result vs. actual result. Include a specific example when possible.

The Silent Failure

The script runs, says “Done!”, but nothing happened:

You: The script said it processed 5 files, but none of them were renamed.

Claude: That suggests the renaming logic isn't reaching the files. Let me add some debugging output to see what's happening at each step.

What to do: Describe what you observed (or didn’t observe). Claude will add visibility to help diagnose.

The Debugging Conversation

Here’s a template for reporting problems:

I ran the [name of script] and something isn't right.

**What I expected:** [describe what should happen]

**What actually happened:** [describe what you observed]

**Error message (if any):**
[paste the full error]

**What I was working with:**
[describe the files, folder, or data you used]

Example:

I ran the file renamer and something isn't right.

What I expected: All PDF files should be renamed to include today's date

What actually happened: Only 2 of 5 PDFs were renamed. The other 3 are unchanged.

Error message: None—the script said "Complete!" but not all files changed.

What I was working with: A folder with 5 PDF files. The ones that weren't renamed have spaces in their filenames.

That last detail—spaces in filenames—is probably the clue Claude needs.

Common Fixes

”File not found”

The script can’t find something. Check:

  • Are you running the script from the right folder?
  • Do the files actually exist with that exact name?
  • Did you use the right file extension (.docx vs .doc)?

Ask Claude:

Can you modify the script to show me which folder it's looking in
and list the files it finds there?

“Permission denied”

The script isn’t allowed to access something. Check:

  • Are you trying to modify a file that’s open in another program?
  • Is the file or folder read-only?

Ask Claude:

I'm getting permission denied. Can you add error handling to skip
files that can't be accessed and report which ones were skipped?

“It only works for some files”

Some files work, others don’t. Check:

  • What’s different about the files that don’t work?
  • Different naming patterns? Different file types? Different contents?

Ask Claude:

This works for some files but not others. The ones that fail have
[describe the difference]. Can you handle those cases too?

“The output format is wrong”

The data is there, but not how you want it.

Ask Claude:

The script works, but the output shows [current format]. I need it
to show [desired format] instead. Can you adjust the output?

Adding Debug Output

When you can’t figure out what’s wrong, ask Claude to add visibility:

The script isn't working as expected. Can you add print statements
that show me:
1. What folder it's looking in
2. Each file it finds
3. What it decides to do with each file
4. The result of each action

Now when you run it, you’ll see exactly what’s happening:

Looking in folder: /Users/you/Desktop/contracts
Found file: agreement.pdf
  Action: Rename to 2024-03-15_agreement.pdf
  Result: Success
Found file: draft notes.docx
  Action: Skip (not a PDF)
Found file: final contract.pdf
  Action: Rename to 2024-03-15_final contract.pdf
  Result: ERROR - Invalid filename character

Now you can see the problem: spaces in filenames cause errors.

When to Start Over

Sometimes a fix is more complex than starting fresh:

This is getting complicated. Let me describe what I actually need
from scratch, and can you build a new version?

I need a script that:
[clear, complete description of requirements]

Please include:
- Handling for files with spaces in their names
- A preview mode that shows what will happen before doing it
- Error handling that skips problem files and reports them at the end

There’s no shame in this. You’ve learned what you need from the debugging process.

Exercise: Practice Debugging

Try this with Claude:

  1. Ask Claude to create a script with a deliberate bug:
Create a script that lists all .txt files in a folder.
But deliberately introduce a subtle bug—something that would cause
it to fail for certain filenames.

  1. Run it on a test folder with various filenames

  2. When it fails, practice the debugging conversation:

    • Describe expected vs. actual behavior
    • Ask Claude what might cause this
    • Work together to fix it

What You’ve Learned

  • Debugging is describing what you expected vs. what happened
  • Error messages tell you what’s wrong—just share them with Claude
  • When stuck, ask Claude to add visibility (print statements)
  • Starting over with better requirements is sometimes the right choice

Next Lesson

You’ve learned the fundamentals: setting up, building, communicating, reading code, and debugging. Now it’s time to apply these skills to real projects. The next lesson guides you through building a complete document organizer you can actually use.