Describing a Bug So Your AI Agent Can Actually Fix It

The one-sentence version: symptom, not diagnosis

The single most common way a well-intentioned bug report still fails is describing what you think is wrong instead of what you're actually seeing. It feels helpful to offer a theory, "I think the database connection dropped," but a wrong theory actively misdirects an AI agent's attention toward the wrong place, which is worse than offering no theory at all. The agent is almost always better positioned than you are to diagnose the real cause, once it has the actual symptom in front of it rather than your interpretation of it.

The four things a fixable bug report always has

Four specific pieces of information cover almost every real bug worth reporting. The exact error text, copied character-for-character, never paraphrased, since an error message is frequently a precise identifier, an exact code or wording, that immediately narrows down the real cause. Where it appeared: a browser console, a deploy build log, or a backend function log all point at genuinely different layers of your app, covered in more depth below. What you did right before it happened, the specific action, not a general area of the app. And what you expected versus what actually happened, stated as two separate, plain sentences rather than folded into one confused description.

Where you'll actually find the error text on a build with no IDE

Without a traditional developer's debugger or terminal, three places cover almost every error you'll run into. Your browser's own developer tools (press F12, or right-click and choose Inspect, then the Console tab) shows frontend errors exactly as your browser sees them. Your platform's own build or deploy log, visible in Lovable, Base44 or Bolt.new's own interface, shows errors from the step that compiles your project before it goes live, covered in this site's own guide to what deployment actually means. A backend function's own log, where Supabase Edge Functions or Base44's backend runtime record what happened server-side, shows errors from code that never reaches your browser at all. Naming which of the three you're reading, not just pasting the text, is itself part of a well-formed report.

Why "I think the API key is wrong" is worse than no theory at all

Offering a wrong diagnosis doesn't just fail to help, it actively costs time: an AI agent given a specific but incorrect theory will often investigate that theory first, checking and ruling out the API key before it gets to the actual cause, a permission issue, a mismatched field name, something else entirely. This site's own Fixes silo exists specifically because real errors on an AI-built site cluster into a small number of actual categories, not the theory a worried builder guesses at under pressure. A precisely described symptom, handed over without a guess attached, reaches the real category faster than a plausible-sounding wrong one ever does.

What a genuinely well-formed bug report looks like, worked example

Our guide to why an AI-built app stops working is built around this same discipline: it starts from the exact error, a 401, a 403 or a 500, and the layer it came from, not a general description of "the backend seems broken." That same specificity is what turns a real bug you're facing into something your own AI agent can act on rather than guess at.

Not every bug reproduces the same way twice

A bug that happens every single time usually points at something wrong in the logic itself, straightforward to describe and fix. A bug that only happens sometimes is worth naming as such explicitly, since it often points at a race condition or a timing-dependent state rather than a simple logic error, the same category this site's own guide to why a vibe-coded app isn't production-ready by default covers with a real worked race-condition example. Saying "this happens every time" versus "this happened once, I haven't reproduced it since" changes what an AI agent should even look for first.