How to Describe a Bug Clearly in English
Describe a bug clearly in English: expected vs actual behaviour, reproduction steps, environment details, and the precise verbs that make a report instantly actionable.
The single most useful skill in any bug report is describing the problem so clearly that another engineer can reproduce it without asking a single question. Most bug reports fail at this. This guide gives you a simple structure and the precise English that turns “it doesn’t work” into a report someone can fix today.
The Golden Rule: Expected vs Actual
Every clear bug description contrasts two things:
- What you expected to happen.
- What actually happened instead.
“I expected the form to submit and show a success message. Instead, the page reloaded and the form was empty, with no error shown.”
If you only describe one side, the reader has to guess the other. Always state both.
A Simple Structure
- Summary — one sentence.
- Steps to reproduce — numbered.
- Expected result.
- Actual result.
- Environment — browser, OS, version, account type.
- Evidence — screenshot, log, error message.
Summary: Uploading a PDF over 5MB fails silently. Steps: 1. Go to Documents. 2. Click Upload. 3. Select a 6MB PDF. Expected: The file uploads and appears in the list. Actual: The progress bar reaches 100%, then nothing happens. No file appears, no error shown. Environment: Chrome 124, macOS, Pro account.
Precise Verbs for Describing Behaviour
Vague verbs slow everyone down. Use precise ones:
| Vague | Precise |
|---|---|
| ”It breaks." | "It throws a 500 error." |
| "It’s weird." | "The list shows duplicate entries." |
| "It freezes." | "The UI becomes unresponsive for about ten seconds." |
| "Nothing happens." | "The button click has no visible effect and logs no request.” |
“The request hangs for thirty seconds, then times out with a 504.”
Describing Frequency and Conditions
Reproducibility is gold. Tell the reader how often and under what conditions:
- “This happens every time.”
- “It’s intermittent — roughly one in five attempts.”
- “It only happens when the user has more than 100 items.”
- “I can’t reproduce it consistently, but it tends to occur after the session has been open for a while.”
“It only fails on mobile Safari; desktop browsers work fine.”
The word “only” is powerful — it narrows the search dramatically.
Including the Error Message Verbatim
Never paraphrase an error. Copy it exactly.
“The console shows:
TypeError: Cannot read properties of undefined (reading 'id')atcart.js:42.”
Paraphrasing (“some error about undefined”) loses the detail that often points straight to the cause.
Words That Add Useful Context
- “This started happening after the last deploy.”
- “It used to work in the previous version.”
- “This is a regression — it worked last week.”
- “It’s a blocker — I can’t continue testing until it’s fixed.”
“This is a regression from version 2.3 — the same flow worked there.”
The word “regression” tells the team that something that worked is now broken, which changes how urgently they treat it.
What to Leave Out
A clear report avoids:
- Guesses about the cause stated as fact (“it’s definitely the database”). Offer them as theories: “my guess is it’s related to caching, but I’m not sure.”
- Emotional language (“this is a disaster”). State impact instead: “this blocks all new sign-ups.”
- Three bugs in one report — file them separately.
A Phrase Bank for Bug Reports
“Steps to reproduce:” “Expected behaviour:” “Actual behaviour:” “This happens consistently / intermittently.” “It only occurs when…” “This is a regression from…” “Attaching a screenshot and the full stack trace below.”
Quick Before-and-After
Before: “Upload is broken, please fix.”
After: “Uploading PDFs over 5MB fails silently on Chrome (steps below). Expected: file uploads. Actual: progress hits 100% then nothing happens, no error. Consistent. Screenshot and console log attached.”
The second version can be fixed today; the first generates a day of questions.
Describing a bug clearly is a gift to whoever fixes it — and often that’s your future self. Contrast expected with actual, number your steps, quote errors verbatim, and state the conditions precisely. Master this simple structure and your bug reports will become the ones developers actually want to pick up.