Errors & Troubleshooting

How to debug an AI-built app without making it worse

Get the exact error, work out which kind of problem it is, then change one thing at a time. Asking your AI to "fix it" without the error makes it guess, and a guess at a settings problem usually rewrites code that was working. Your job is to give it the evidence; its job is to explain the cause before it changes anything.

1. Copy the exact error. Word for word, from the screen, the browser's console or your host's log. A description ("it doesn't load") gives the AI nothing to work with.
2. Note what changed. A new feature, a new key, a deploy, a setting you changed. Most breaks follow a change.
3. Name the kind of problem. Use the table below. It decides where the fix lives: in the code, in a setting, or with another service.
4. Ask for the cause before the fix. The prompt further down does this for you.
5. Change one thing, then test. Save a restore point first (Git, or your builder's version history), so a wrong fix can be undone.

Which kind of problem is it?

Start from what you can see. Each row points to the guide that explains the cause and the fix.

Why AI-built apps break at the joins

AI coding agents are good at writing an app's own logic. Most of what breaks later sits where that logic meets something else: a service your app calls, a database with permission rules, a host with its own settings, or a search engine reading the result. Each of those has settings that live outside the code the AI wrote, and the AI can't see them unless you show it. That's why "the code looks fine" and "it doesn't work" are so often both true at once.

It's also why re-prompting in different words rarely helps with this kind of fault. If a key is missing on your live host, no change to the code will put it there. The fix is to find which join failed and check that setting, then change the code only if the setting turns out to be right.

When the problem is the conversation, not the app

Some failures feel like bugs but aren't. If your AI fixes one thing, breaks another, then brings the first bug back, or starts forgetting what you told it earlier, the app may be fine and the conversation is the problem. Breaking a vibe-code loop and knowing when to start a new chat cover the way out, and describing a bug to your AI covers how to write the report in the first place.

What your AI can't do for you

• It can't see your host, your services or your logs unless you paste what's there. If the fix depends on a setting outside the chat, you'll be the one who checks it.
• It can't fix another service being down. A 502 or 503 from a service you call can be their problem, not yours. Check the service's status page before you change anything.
• It doesn't know that its answer worked. It will often say "this should fix it". Only a test on the same page, in the same place the error happened (preview or live), tells you it did.
• A fix written for someone else's setup may not fit yours. Advice from a forum post was written for a different project, tool or host. Give your AI your error and your setup, not someone else's fix.

A prompt to start any debugging session

Fill in the brackets and paste it into your AI coding agent's chat. It asks for the cause first, so nothing changes until you both agree what's wrong.

I'm not a coder. Something in my app is broken.

What I did: [the steps, e.g. "clicked Pay on the
checkout page"]
What I expected: [what should have happened]
What happened instead: [what you saw]
The exact error: [paste it word for word, from the
screen, the browser console or the host's log]
Where it happens: [preview only / live site only /
both]
What changed since it last worked: [anything you
remember, or "not sure"]

Don't change any code yet. First:
1. Tell me which kind of problem you think this is:
   a setting or key, a permission rule, a deploy
   setting, a problem with another service, or the
   app's own logic.
2. Tell me why, based on the error.
3. Tell me what you'd check first to confirm it, and
   anything I need to look at myself that you can't
   see (a host setting, a service's dashboard, a log).

Only once we agree on the cause, suggest one change.

What to check in the AI's answer

• The kind of problem matches your error. A 401 blamed on a layout bug, or a blank live site blamed on code that works in preview, is worth questioning.
• It names something you can check. A specific setting, file, key name or log, not "there may be a configuration issue".
• It asks you for what it can't see. If the cause could be on your host or with another service, it should say so and tell you what to look at.
• It proposes one change. A plan that rewrites several files at once to fix one error is a sign it's guessing. Ask it to narrow down first.