How to explain a bug with a screenshot

A bug screenshot is an image that shows the exact problem, so the person helping you sees what you see. On a Mac you have 3 built-in ways to capture it: the entire screen, one window, or a selected portion (Apple Support).

You know the problem. You have been looking at it for ten minutes. The person helping you has not seen it at all.

A clear screenshot can close that gap. It gives you both the same starting point, without a long message or a meeting.

Capture the part that explains the problem

Include the thing that went wrong and enough of the surrounding screen to make sense of it. A button without its label or an error without the page around it can create more questions.

For a small visual problem, an area screenshot is usually enough. If the problem is tied to a whole app window, include that window. You do not need to share your entire desktop to explain one broken button.

Give the reader one clear place to look

Use an arrow, a box or a short note to point to the problem. One good mark is often more useful than a screen full of marks.

For example, write “This button does nothing” beside the button. That says more than “Broken”, and the reader does not have to guess what you mean.

If two things need attention, number them. Match those numbers to the steps in your message.

Check for private information

Before you share, look for email addresses, customer names, account details and access keys. Remove or hide anything the person helping you does not need.

Pay particular attention to browser tabs, sidebars and notifications. Private information often sits outside the part you meant to show.

Add three short lines

The image shows the problem. Your message should explain the context:

1. What I did: “I opened Settings and clicked Export.”
2. What I expected: “I expected a file to download.”
3. What happened: “Nothing opened, and this message appeared.”

If the problem happens only sometimes, say that too. Include the app version and your macOS version when they could help someone reproduce it.

Use a recording when the steps matter

Some bugs are about movement or timing. A menu closes too early. A drag stops halfway. Something appears for a second and disappears.

A short screen recording can show the sequence more clearly than five separate images. Start just before the problem and stop once it is visible. Review the clip before sharing, just as you would a screenshot.

Make the next step easy

Open the image or shared link once before you send it. Make sure it shows the version you meant to share and that the important text is readable.

Znip brings screenshots, annotations and screen recordings into one Mac app, so you can make that explanation in one place. It is currently in invite-only beta. If you would like to try it, request an invite.

And if you are reporting a problem with Znip itself, tell us what happened at hey@znip.app. A clear picture and those three short lines are a great start.

Frequently asked questions

What should a bug screenshot include?

Include the thing that went wrong and enough of the screen around it to make sense. A button without its label, or an error without its page, usually leads to more questions.

Should I send a screenshot or a screen recording?

Send a screenshot when one picture shows the problem. Send a short recording when the steps or timing matter. On a Mac, Shift, Command, 5 opens a toolbar that does both (Apple Support).

How do I keep private details out of a bug screenshot?

Capture only the window or area you need, not your whole desktop. Then check the image for names, emails and passwords before you send it.

By Siddharth Sharma, who builds Znip.