How to record a bug report video developers can use

"It doesn't work" is the least useful bug report there is. A good written report helps, but a short screen recording often does more: the developer sees exactly what you clicked, in what order, and what happened. No guessing about which button you meant or what "it froze" looked like. This guide covers how to record a bug report video that actually gets the bug fixed: what to show, how long it should be, what to hide, and where to put it.

Why video helps

Developers fix bugs fastest when they can reproduce them. Written steps leave gaps: you forget the step that felt obvious, or you describe the screen in different words than the code uses. A video fills those gaps. It shows the starting state, the exact sequence, the timing (some bugs only happen if you click fast) and the result.

A video doesn't replace the written report, though. Developers search issues by text, skim them in triage, and copy error messages. The best bug reports have both: a short written summary and a video that proves it.

What a good bug video shows

Think of it as a short, boring film with a clear plot.

1. The starting point. Begin on a screen the developer recognizes: the page URL visible, the account or project you're in, the state before anything goes wrong. A second or two is enough.
2. The steps, at normal speed. Do exactly what you did when the bug happened. Don't rush, and don't narrate over the important part with a long story.
3. The bug itself. Let it happen and stay on it for a few seconds. If it's an error message, keep it on screen long enough to read.
4. The evidence. If you can, open the developer tools console or network tab and show the error. For a desktop app, show the log or crash dialog.
5. The expected result (optional). If it's not obvious, say or show what should have happened.

Do the steps once. If you need two attempts to trigger the bug, keep both: "it happens about half the time" is useful information.

Keep it short

Aim for under two minutes, and under 30 seconds when possible. Long videos get watched at 2× speed or not at all. If the setup takes a long time (for example, filling a long form), either trim it or speed it up in editing so the developer still sees that it happened.

If you're narrating, keep it factual: "I'm on the invoice page, I change the currency to euro, I click Save... and the total goes back to dollars."

Show what's invisible

Some things matter for a bug but don't show up in a plain screen recording:

• Keyboard shortcuts. If you pressed ⌘Z or Tab, the video just shows something changing. A keystroke overlay shows each key as you press it.
• Clicks. A visible click effect shows exactly when and where you clicked, including double-clicks and clicks that did nothing.
• Small details. If the bug is a one-pixel misalignment or a tiny wrong number, zoom in on it so it's readable when the video is played small inside an issue.

Hide what shouldn't be there

Bug reports end up in issue trackers, sometimes public ones. Before you share, check the recording for:

• API keys, tokens and passwords (in terminals, settings pages, .env files)
• Real customer names, emails, addresses and payment details
• Internal URLs, Slack messages and notifications that pop up mid-recording
• Personal browser tabs and bookmarks

The safest approach is to record in a test account or staging environment. If something sensitive is in the shot anyway, blur it before sharing; don't just hope nobody pauses on that frame.

Include the environment in writing

Next to the video, write down the facts the video can't show reliably:

Copy any error message as text too. Text is searchable; video isn't.

MP4 or GIF?

• MP4 for anything with sound, anything longer than about 15 seconds, and anything where detail matters. It's much smaller than a GIF for the same clip.
• GIF for a short, silent loop that should play right inside the issue without clicking play, like a flickering button or a broken animation.

GitHub, Jira and Linear all accept file uploads in issues and comments. On GitHub, the documented limits are 10 MB for images and GIFs, and 10 MB for videos in repositories owned by free-plan users or organizations (100 MB on paid plans). Jira and Linear have their own attachment limits, set by your workspace; a 1080p MP4 of under a minute is usually well within them.

Recording a bug report with Dolly

Dolly is a Mac screen recorder; this is how a bug report video works in it:

1. Record a window or area. Press ⇧⌘2 and pick the app window, or draw an area around the part that matters. Smaller areas make smaller, sharper files.
2. Turn on the keystroke overlay if shortcuts are part of the bug. It needs Input Monitoring permission once.
3. Reproduce the bug. Use the microphone if you want to narrate. Pause or restart the take from the floating pill if something goes wrong.
4. Trim. Cut the start and end, split with S, and speed up long waits so the developer still sees them.
5. Zoom in on the bug. Clicks become zooms automatically; delete the ones you don't need and press Z to add one on the exact moment it breaks.
6. Blur secrets. Draw a blur mask over tokens, emails or customer data. Masks have their own track on the timeline, so you can blur only the seconds that need it.
7. Export and attach. Export an MP4 at 1080p (or a GIF for a short loop), or copy it to your clipboard and paste it straight into the issue.

Attach the file itself, which is what most issue trackers prefer: the video stays with the issue. If your tracker limits file sizes, click Get link instead (Dolly links) and paste the short link. Everything else happens on your Mac; nothing is uploaded unless you upload it or choose Get link.

More on this in bug reports with Dolly, or see how the same setup works for README GIFs. Dolly is free, with no time limit; download it here.

Checklist

• [ ] The video starts on a recognizable screen (URL or app state visible).
• [ ] Steps are shown once, at normal speed.
• [ ] The bug stays on screen long enough to read.
• [ ] Console or log errors are shown, and copied as text in the issue.
• [ ] No keys, passwords or customer data are visible.
• [ ] Version, OS, browser and frequency are written next to the video.
• [ ] The file is under your tracker's size limit.

A two-minute recording can save a developer an hour of trying to reproduce your bug. That's usually the fastest way to get it fixed.