Quick summary
How to write a bug report, the short answer: give it a specific title, numbered steps to reproduce, the expected result and the actual result, the environment (version, browser, device, account) and evidence (screenshot, error, log). Say how often it happens, and file one bug per report.
What matters most: the steps to reproduce. In a survey of Apache, Eclipse and Mozilla developers, steps to reproduce stood out as the most important item, and incomplete information was by far the most common problem.
When a customer found the bug: support writes the report, links the ticket and notes how many customers are affected, so someone can tell them when it is fixed.
How to Write a Bug Report at a Glance
| Field | What to write | Example |
|---|---|---|
| Title | The problem, in about 10 words | Invoice CSV export is empty when a date filter is set |
| Steps to reproduce | Numbered, one action each, from a known start | 1. Sign in as an Admin. 2. Open Billing, then Invoices... |
| Expected result | What should have happened | A CSV with one row per October invoice |
| Actual result | What happened instead, as an observation | A CSV with the header row only |
| Environment | Where it happened | Production, Chrome 130 on macOS 15, Acme account |
| Reproducibility | How often | Every time, 5 of 5 tries |
| Evidence | Proof and clues | Screen recording, error message, request ID |
| Impact (customer bugs) | Who is affected, and the ticket | 3 customers, link to the support ticket |
Before you write a word, check three things:
Answer these first
- Can you make it happen again? Try once more yourself, ideally on a clean account or browser, so you know the steps work.
- Has it already been reported? Search the tracker first. Adding your details to the existing bug is worth more than a duplicate.
- Is it one bug or several? If two things went wrong, write two reports.
In this article
1.
2.
3.
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
What a Good Bug Report Contains
A bug report has one job: to let someone who wasn't there see the bug for themselves, and then know when it is fixed. As Simon Tatham puts it in his widely read essay on reporting bugs, "When you report a bug, you are doing so because you want the bug fixed." Every field below serves that goal.
Title
The problem in about 10 words. It is the first thing a triager reads, and it is how the next person finds the bug before filing a duplicate.
Steps to reproduce
The numbered path from a known starting point to the bug. This is the part developers rely on most.
Expected result
What should have happened after the last step.
Actual result
What happened instead, written as an observation, not a theory.
Environment
The app version or release, browser and operating system, device, and the account or plan if your product behaves differently per customer.
Reproducibility
Every time, sometimes, or once. A bug that happens one time in five needs more detail than one that happens every time.
Evidence
A screenshot or screen recording, the exact error message, a request ID, a log excerpt, or a sample file.
Severity and priority often appear on the list too. Who sets them depends on your process: in many teams the reporter suggests a severity and the person triaging sets the priority. Our guide to bug severity vs priority covers the difference.
How to Write a Bug Report, Step by Step
- 1
Reproduce it once more
Follow your own steps again and write them down as you go. If it does not happen a second time, note what you did and say so in the report.
- 2
Search for an existing report
Search the tracker for the error message or the feature name. If it exists, add your environment and evidence there instead.
- 3
Write the title last, but put it first
Once you know exactly what broke, describe it in about 10 words. Name the problem, not your suggested fix.
- 4
List the steps to reproduce
Numbered, one action per step, starting from a state anyone can recreate.
- 5
State expected and actual results separately
Two short lines. Facts only.
- 6
Add environment, frequency and evidence
Version, browser, device, account, how often, and a screenshot, recording or error.
- 7
Read it as a stranger would
Could an engineer who has never seen this screen follow it without asking you anything? If not, fill the gap now.
Writing the Bug Report Title
Mozilla's bug writing guidelines ask for a summary of approximately 10 words that "should explain the problem, not your suggested solution." Their examples make the point: "Cancelling a File Copy dialog crashes File Manager" is good, "Software crashes" is not.
| Weak title | Strong title |
|---|---|
| Export broken | Invoice CSV export is empty when a date filter is set |
| Login issue | SSO users see "Invalid credentials" after the Okta redirect |
| Make the dashboard faster | Dashboard takes 40 seconds to load for accounts with 10,000+ tickets |
| Bug in settings | Saving notification settings resets the time zone to UTC |
A strong title names the feature, the failure and the condition. The condition ("when a date filter is set") is often the most useful part, because it tells the developer where to look.
How to Write Steps to Reproduce
Steps to reproduce are where most bug reports fail. Mozilla's guidelines call them "the most important part of any bug report," because "if a developer is able to reproduce the bug, the bug is very likely to be fixed." Five rules keep them usable:
Start from a known state
"Sign in as an Admin on an account with at least one October invoice" beats "Go to the invoices page", because the developer can recreate it.
One action per step, numbered
Numbers make it easy to say "it fails at step 3" and easy to spot a missing step.
Use exact inputs
The real date range, the file you uploaded, the value you typed. Vague inputs are a common reason a bug "can't be reproduced".
Say how you did it
Tatham's advice is to be specific: "I selected Load" might mean clicking a button or pressing a shortcut. If there are two ways to do something, say which one you used.
Stop at the bug
The last step is the action that triggers the problem. What went wrong belongs in the actual result, not in the steps.
If you can only reproduce the bug sometimes, say so plainly ("about 1 in 5 tries") and add everything that differs between the runs that failed and the ones that did not. Mozilla's guidelines note that a bug you can reproduce only occasionally needs additional information to be useful.
Expected Result vs Actual Result
Write them as two separate lines, right after the steps. The expected result is what the product should have done. The actual result is what it did. Mozilla asks reporters to "clearly separate facts (observations) from speculations", and Tatham makes the same point: "Leave out speculations if you want to, but don't leave out facts."
Write this
- Actual: the CSV has the header row and no data rows
- Actual: the page shows 'Something went wrong (500)' and the request ID 7f3a
- Expected: the invoice list keeps the date filter after export
Not this
- It doesn't work
- The export seems broken, probably a timezone bug
- Same as before
If you think you know the cause, add it under a separate "Notes" line, clearly marked as a guess. A wrong theory in the actual result can send a developer down the wrong path.
Bug Report Example: Bad vs Good
Here is the same bug written twice. It is an illustrative example of a typical B2B SaaS bug.
The good version:
Title: Invoice CSV export is empty when a date filter is set
Environment: Production, Chrome 130 on macOS 15
Account: Acme Logistics (Business plan), user role Admin
Reproducible: Every time (5 of 5 tries)
Steps to reproduce:
1. Sign in as an Admin on an account with at least one invoice dated October 2026.
2. Open Billing, then Invoices.
3. Set the date filter to October 1 to October 31, 2026.
4. Click Export CSV.
Expected result: A CSV with one row per October invoice.
Actual result: A CSV with the header row only. Without the date filter, the
export contains every invoice.
Impact: 3 customers have reported it since November 2. Their finance teams
export invoices monthly.
Evidence: Screen recording attached. The export request returns 200 with 0 rows.
Support ticket: link to the HubSpot ticket
The good version takes five minutes longer to write and saves the developer the round trip of asking for every one of those details. It also contains a clue (the export works without the filter) that narrows the search before anyone opens the code.
What Developers Actually Need From a Bug Report
The best evidence on this comes from a study by Thomas Zimmermann and colleagues, published in IEEE Transactions on Software Engineering in 2010. They surveyed developers and bug reporters on the Apache, Eclipse and Mozilla projects.
The study found "an information mismatch between what developers need and what users supply." Developers valued steps to reproduce, stack traces and test cases most, and those are exactly the items reporters found hardest to provide. Surprisingly, mandatory fields such as version, operating system and hardware ranked relatively low in importance, though the authors caution they can still be needed to reproduce or triage a bug.
The biggest causes of delay are not wrong information, but absent information.
The practical lesson: a short report with real steps beats a long report full of fields and no path to the bug.
A Bug Report Template You Can Copy
Paste this into a doc, an issue template or a ticket note. For a fuller field list and when to graduate from a spreadsheet, see our bug tracking template.
Title: [Feature] [what fails] [when / under which condition]
Environment: [production / staging], [browser + version], [OS / device]
Account: [customer or test account], [plan], [user role]
Reproducible: [every time / sometimes (x of y) / once]
Steps to reproduce:
1.
2.
3.
Expected result:
Actual result:
Evidence: [screenshot / recording / error message / request ID / log]
Impact: [number of customers affected, workaround if any]
Support ticket: [link]
Notes (guesses, clearly marked):
Writing a Bug Report From a Customer Ticket
In B2B SaaS, many bugs are found by customers and written up by support. That changes the job. The Zimmermann study found reporters struggle most with exactly the details developers want, and customers are the extreme case: they know what they saw, not how to reproduce it.
- 1
Ask targeted questions, once
What did you click, what did you expect, what happened, and roughly when? Ask for a screenshot or recording and the browser. Our bug report reply templates include one for asking for repro steps without sounding like a form.
- 2
Reproduce it yourself
On the customer's account if you can, or on a test account set up the same way. Steps you have run yourself are worth far more than steps relayed from an email.
- 3
Keep the facts on the ticket
If bugs are a regular part of your queue, create custom ticket properties for the facts you always need, such as steps to reproduce, impact and affected feature. They are filled once and stay with the ticket.
- 4
File one issue and count the customers
Search for the bug first. If it already exists, link the ticket to that issue rather than filing a duplicate, so the issue shows how many customers hit it.
- 5
Link the ticket to the issue
The developer can read the original conversation, and support knows which issue to watch.
That last step is the one most teams skip, and it is why customers wait on tickets for bugs that shipped weeks ago. Our bug triage guide covers how support and engineering agree on what gets fixed first.
Make Good Bug Reports the Default: Forms and Templates
Asking people to "write better bug reports" rarely lasts. Making the tool ask for each field does. Most trackers and help desks can now do this:
Linear form templates
Form templates add structured fields to the issue form, and any field can be required. They work in Linear, in the Slack integration and in Asks, and can be the default template for people outside the team. Our Linear bug tracking guide walks through building one.
GitHub issue forms
A YAML file in the repository's
.github/ISSUE_TEMPLATEfolder defines input fields, validations such as required fields, default labels and assignees. GitHub lists issue forms as public preview.HubSpot help desk forms
On Service Hub Professional or Enterprise, a form connected to help desk creates a ticket for every submission, with ticket properties set from the form. A bug report form on your support site can collect the repro fields from the customer up front.
The Most Expensive Mistake: A Perfect Report That Never Reports Back
A well-written bug report gets the bug fixed. It does not, on its own, get the customer told. The engineer closes the issue, the release goes out, and the support ticket that started it all sits untouched until the customer asks again.
A bug report is finished when the customer who found the bug hears it is fixed, not when the issue closes.
The fix is a two-way link between the ticket and the issue: the issue carries the ticket, and the ticket hears when the issue changes.
Bug Reports From HubSpot Tickets to Linear
If your support team works in HubSpot Service Hub and engineering works in Linear, there is no native path between them: Linear's support integrations cover tools such as Zendesk and Intercom, not HubSpot. IssueLinker is a HubSpot Marketplace app that turns a ticket into a complete Linear bug report.
File from the ticket
A card on every ticket creates a Linear issue or links an existing one, so a second customer with the same bug joins the original issue. It can draft the title and description with AI from the ticket conversation.
Bring the evidence
Screenshots and file attachments from the ticket are carried into the new issue, and the issue links back to the HubSpot ticket.
Carry the repro facts with Ticket details
Pick the ticket properties that hold your bug facts, such as steps to reproduce or impact, and IssueLinker adds them to every new Linear issue under a Ticket details heading. Empty properties are skipped, so reps never retype what is already on the ticket. It is an opt-in setting.
Use your Linear templates
On Service Hub Professional, the Create Linear issue from template workflow action files the bug with one of your Linear issue templates, so automated reports get the same labels and structure as manual ones.
Report back
Comments sync both ways, so an engineer asking for one more detail reaches the rep on the ticket. The Linear status, assignee and priority are written to ticket properties, and optional status emails tell the ticket owner when the issue is closed.
The card works on any HubSpot plan. See the HubSpot Linear integration, or compare every option in our Linear HubSpot integration guide.
Bugs reported in HubSpot, fixed in Linear?
IssueLinker turns HubSpot tickets into complete Linear issues, syncs comments both ways, and writes the Linear status back to the ticket. $39 per month flat, unlimited users, 14-day free trial.
Who This Guide and IssueLinker Are Not For
The writing advice above applies to any tracker. IssueLinker only fits if your support runs on HubSpot and engineering uses Linear, Jira or GitHub. If your support runs on Zendesk, Intercom or Front, Linear connects to those natively. And if your bugs are found only by engineers and QA, a good template in your tracker is all you need.
