Troubleshooting
What to do when things break.
Things will break. This is not a sign you did something wrong. This is how software development works. Here's how to get unstuck.
The troubleshooting mindset: When something breaks, you're not failing. You're debugging. Professional developers spend 30-50% of their time fixing things that don't work. The difference between a beginner and an expert is that the expert has seen more errors. Every bug you fix makes you better at this.
The Screen Is Blank
You load your app or artifact and see... nothing. White screen. No errors visible.
Problem: The artifact preview is completely blank/white
Fix: This usually means a JavaScript error happened before anything could render. Ask Claude: "The artifact is showing a blank screen. Can you check for JavaScript errors and fix them?"
Problem: The deployed site shows a blank page
Fix: Open browser developer tools (F12 or right-click > Inspect > Console). Copy any red error messages and paste them to Claude: "My deployed site is blank. Here's the console error: [paste error]"
Problem: Part of the page loads but some sections are missing
Fix: A component is failing silently. Tell Claude: "The [header/form/button/etc] isn't appearing. The rest of the page loads fine. What's wrong with that component?"
Common Error Messages (Translated)
Error messages look scary but they're usually telling you exactly what's wrong. Here are the most common ones in plain English:
| Error Message | What It Means |
|---|---|
| Cannot read property 'X' of undefined | Code tried to use something that doesn't exist yet. Usually a timing issue. |
| Module not found | A library or file is missing. Claude needs to add it. |
| Unexpected token | Typo in the code. Missing bracket, comma, or quote somewhere. |
| CORS error | Security block when talking to another website's data. Need server-side fix. |
| 404 Not Found | The URL or file path is wrong. Check spelling. |
| Build failed | Vercel couldn't turn your code into a website. Scroll up for the real error. |
Copy this to Claude when you see an error:
I'm getting this error: [paste the full error message]
It happens when I [describe what you were doing].
Can you explain what this means and fix it?
When Claude Gets Confused
Sometimes Claude loses track of what you're building, gives contradictory answers, or starts making things worse instead of better.
Problem: Claude's fixes keep breaking other things
Fix: This usually means the conversation has gotten too tangled. Start a new chat and give Claude a fresh, clear summary of what you have and what you need.
Problem: Claude gives different answers to the same question
Fix: The conversation context is confusing it. Copy your current working code, start fresh, paste the code, and ask your question again.
Problem: Claude keeps suggesting things you've already tried
Fix: Tell it explicitly: "I already tried [X, Y, Z] and they didn't work. What else could be causing this?"
Problem: Claude's response doesn't match what you asked
Fix: Your prompt might be ambiguous. Rephrase with more specific details: "When I click the Submit button, I expect [X] to happen, but instead [Y] happens."
The nuclear option: If nothing is working and you're 30+ minutes into debugging with no progress: stop. Copy your most recent working version (or your original blueprint if nothing ever worked). Start a completely new conversation. Explain what you want from scratch. Sometimes the fastest path forward is to start over with everything you've learned.
Deployment Problems
Your artifact works perfectly in Claude. Then you deploy and everything breaks.
Problem: Works in Claude, broken when deployed
Fix: Artifacts have access to things (like localStorage simulation) that real deployments don't. Tell Claude: "This worked in the artifact but breaks when deployed. The error is [X]. What's different about the deployment environment?"
Problem: Vercel shows "Build Failed"
Fix: Scroll up in the Vercel build logs to find the actual error. It's usually near the first red text. Copy that specific error and ask Claude to fix it.
Problem: Site deploys but shows old version
Fix: Clear your browser cache (Ctrl+Shift+R or Cmd+Shift+R). If still old, check Vercel dashboard to confirm the new deployment finished.
Problem: Can't push to GitHub / authentication error
Fix: Your GitHub credentials may need refreshing. In Claude Code, ask: "I'm getting a GitHub authentication error when trying to push. How do I fix this?"
The rollback safety net: If you deploy something and it breaks badly, Vercel lets you instantly rollback to the previous working version. Go to your project in Vercel > Deployments > click on a previous successful deployment > click "Promote to Production." Your broken deploy is undone. Breathe.
When to Start Over vs. Keep Pushing
The hardest judgment call in debugging: do you keep trying to fix what you have, or cut your losses and start fresh?
Keep pushing if:
- You understand what's wrong (even if you don't know the fix)
- Each iteration is making progress, even if slow
- The problem is isolated to one part of the app
- You've tried fewer than 5 different fixes
- Claude's explanations make sense to you
Start over if:
- You have no idea what's wrong
- Fixes keep breaking other things
- The whole app feels unstable
- You've tried 5+ fixes with no progress
- Claude seems as confused as you are
- You've been debugging longer than it took to build the original
Starting over is not failure: Starting over with a clearer prompt and fresh context often gets you to working code faster than continuing to patch something broken. You're not losing progress - you're using what you learned. The second attempt is always faster because you know what you actually want.
Copy-Paste Scripts for Stuck Moments
When you're stuck, grab the appropriate script:
When nothing is rendering:
The screen is blank/white. No visible errors. Can you add console.log statements to figure out where it's failing, then fix it?
When you have an error message:
I'm getting this error: [paste error]
Explain what this means in plain English, then fix it.
When it worked before but now it doesn't:
This was working until we made the last change. Can you undo the last change and show me what it looked like before?
When Claude's fixes aren't helping:
We've tried several fixes and none are working. Let's step back. Can you explain what you think is happening, and what the top 3 most likely causes are?
When you want to start fresh:
Let's start over. Here's what I want to build: [paste your blueprint]. Here's what I learned from the last attempt: [list 2-3 things]. Build a new version from scratch.
When deployment fails:
The build failed with this error: [paste error from Vercel logs]. What's wrong and how do I fix it?