Igor Yussupov
To report a bug to a developer, tell them five things: what you were trying to do, what you did, what happened, what you expected, and where it happened (the page address, your browser and the account you used). Add a screenshot with the problem marked, and send one bug per message. You do not need to know why it broke. You only need to describe what you saw clearly enough that the developer can see it too. This guide is written to be forwarded to clients and colleagues, so it avoids jargon.
The five things a developer needs
- What you were trying to do. The goal, not the click. "I was trying to download last month's invoice" tells the developer which feature to look at.
- What you did. The steps, in order, from where you started. "I logged in, opened Invoices, clicked March, clicked Download."
- What happened. Exactly what you saw. Copy any error message word for word. "Nothing happened" and "a red box appeared saying 'Something went wrong'" are very different reports.
- What you expected. What you thought would happen. Developers cannot always tell what is wrong unless they know what you thought was right.
- Where it happened. The address of the page (copy it from the top of the browser), the browser you use and the account or customer you were logged in as. Mention if it also happens on another device.
If you give only these five, you have given most developers what they need. The same list, written for people who write bug reports every day, is in what developers need in a bug report.
A message you can copy
Paste this into an email or a chat message and fill it in:
Subject: [Short description] on [page name]
What I was trying to do:
[one sentence]
What I did:
1. [step]
2. [step]
3. [step]
What happened:
[what you saw, and any error text, copied exactly]
What I expected:
[what you thought would happen]
Where:
Page: [address of the page]
Browser: [for example Chrome 141 on Windows]
Logged in as: [account or customer]
When: [date and time, if you can]
How often:
[every time / sometimes / once]
A screenshot is attached.A filled-in example:
Subject: Invoice download does nothing on the Invoices page
What I was trying to do:
Download the March invoice for Acme Ltd.
What I did:
1. Logged in
2. Opened Invoices
3. Clicked March
4. Clicked Download
What happened:
The button turned grey for a second, then nothing. No file arrived and no message appeared.
What I expected:
A PDF to download.
Where:
Page: https://app.example.com/invoices/2026-03
Browser: Chrome on Mac
Logged in as: accounts@acme.example
When: today, about 10:15
How often:
Every time. February downloads fine.
A screenshot is attached.The last line of the example is worth copying. "February downloads fine" tells the developer that the problem is with March's data, which saves them an hour.
What to attach
- A screenshot with the problem marked. Draw a circle or an arrow around the wrong thing. A bare screenshot of a full page leaves the developer to guess which part you mean.
- The whole window, including the address bar. It shows the page, the browser and the time if your clock is visible.
- The exact error text. If a message appears, copy it into your message too, so it can be searched.
- A short screen recording for problems that happen over time, such as something that flickers, loads slowly or only breaks after several steps.
- The file or data you used, if the problem happened when you uploaded or entered something. Make sure it contains nothing private first.
How to find your browser and take a screenshot
Your browser version. In Chrome, open the menu (three dots, top right), choose Help, then About Google Chrome. In Safari, choose Safari then About Safari. In Edge, open the menu, then Help and feedback, then About Microsoft Edge. If you cannot find it, the browser's name and your device are better than nothing.
A screenshot on Windows. Press the Windows key, Shift and S together, then drag around the area. On a Mac, press Command, Shift and 4, then drag. On a phone, press the power and volume buttons together, or follow your device's instructions.
What to leave out
- "It's broken." Without a description, the developer cannot tell what you mean by broken.
- Several bugs in one message. They get lost, and one cannot be closed without the others. Send each one separately.
- Guesses about the cause. "I think the database is down" can send a developer in the wrong direction. Say what you saw and let them find the cause.
- Passwords and private data. Never include a password, a payment card number or personal details in a screenshot or a message. Cover them first.
- Anger. It is understandable, and it does not speed anything up. Facts do.
Tools that do the technical part for you
If you report bugs often, a tool can capture the technical part so you do not have to. With SnagRelay, you click Report on the page where the problem is, point at the thing that is wrong and write what you expected. The page address, your browser, the error messages, the failing requests and the steps are attached for you, and the report goes to the developer's tracker. On paid plans you can also mark up a screenshot and black out private details before sending. You do not need an account to report with the widget, and when the developer marks the problem fixed you get an email. See marking up a bug on the page or the SnagRelay home page for how it works.
FAQ
What information should I include when reporting a bug?
What you were trying to do, the steps you took, what happened (with any error text), what you expected, and where it happened: the page address, your browser and the account you used. Add a screenshot with the problem marked.
Do I need to know why the bug happens?
No. Describe what you saw. Finding the cause is the developer's job, and guesses can mislead them.
How do I explain a bug to a developer who cannot see my screen?
Describe the steps in order, say what you expected and what appeared instead, and attach a screenshot with the problem circled. For a problem that is hard to describe, record your screen for 20 seconds.
Should I send a screenshot or a video?
A marked-up screenshot is enough for something you can see on one screen. A short video helps when the problem involves movement or several steps. Many people send both.