How to Track Visual UI Bugs in Jira

A useful visual UI bug in Jira needs more than a screenshot: include the affected page and state, steps to reproduce, what appeared, and what should have appeared. Then attach the screenshot directly to the Jira work item and confirm that its preview is available to the people who need to triage it.

1. Check for a duplicate before reporting

Search the project or Jira work items for the same page or component and visible symptom. A duplicate can split discussion and evidence across multiple reports. Choose the reporting path that matches the situation: report an identified bug, raise a suggestion about behavior, or request support when you need help. Atlassian recommends checking for existing work items and distinguishes these reporting paths.

2. Create a specific bug report

Use a summary that identifies where the problem appears and what is visibly wrong. For example, “Checkout: selected shipping option loses focus outline.” This is an illustrative title, not a report from a tested Jira instance.

In the description, provide enough detail for another person to reproduce the problem. Atlassian advises including sufficient detail to help the person resolving the issue. The following template is a practical way to organize that information; it is not an Atlassian-prescribed visual-bug schema. See Atlassian’s guidance on issue descriptions.

Summary: [Page or component] — [visible defect]

Environment: [browser, device, viewport, and relevant account state; record only what is known]

Preconditions: [state needed to reach the affected view]

Steps to reproduce:
1. [First action]
2. [Next action]
3. [Action that reveals the defect]

Actual result: [What appeared, including the affected element and visible state]

Expected result: [What should appear or how the interface should behave]

Evidence: [Screenshot attached to this Jira work item; identify the relevant region if needed]

Keep actual and expected results separate. Record the browser, viewport, and account state when they matter, but do not guess at unknown environment details. If a short recording communicates a motion or timing problem better than a still image, it can be supporting evidence when your team permits it; Jira supports video files among attachments. Atlassian’s attachment guidance covers supported attachments.

3. Capture useful screenshot evidence

Capture the state that demonstrates the defect. Include enough surrounding interface to establish context, while keeping the affected control or region easy to find. If the issue depends on a particular viewport or state, note those details in the report. Add a short evidence note naming the relevant region when the image contains multiple elements.

A screenshot supports the written report; it does not replace reproduction steps. Avoid relying on an externally hosted image link as the only evidence. Upload the file to Jira so it is stored with the work item and does not depend on another service’s availability or permissions. Atlassian specifically recommends uploading an image as an attachment when an external image preview is unavailable. See Atlassian’s image-preview troubleshooting guidance.

4. Attach the screenshot to the Jira work item

Open the existing work item or create the bug report.
Drag the screenshot file onto the work item, or use the attachment or Add controls available in your Jira interface.
If you are adding evidence to a long text field, use the image or file controls there; Jira supports adding files and images to descriptions, comments, and other long text fields.
Wait for the upload to finish, then open the attachment or preview.
Confirm the attachment is visible to the intended reviewers and that the preview shows the relevant state.

Jira’s work-item experience is rolling out, so control names and locations can differ by site. Atlassian documents drag-and-drop and attachment controls.

5. Verify the report is actionable

The summary identifies the affected page or component and the symptom.
The description records relevant environment and preconditions without speculation.
Steps are ordered and specific enough for a teammate to follow.
Actual and expected results are distinct.
The screenshot is attached to the Jira work item and its preview is available.
The intended reviewers can access the attachment.

Jira displays attachments as a list when a work item has more than 150 attachments, so identify the relevant screenshot clearly if the issue has accumulated evidence over time. Check the current attachment guidance for your interface.

6. Jira attachment settings and edge cases

Permissions and field visibility

Attachments are enabled by default according to Atlassian’s administration documentation, but administrators can change the setting or disable attachments. A custom permission scheme may require the Create Attachments permission. If users need to add a file while creating a work item, the Attachment field must not be hidden for that work type. Ask a Jira administrator to check these settings when upload controls are missing or access is denied. Atlassian’s attachment administration page describes these controls.

File-size limits and storage

Atlassian’s current help pages give conflicting default per-file size figures: one add-content page says 10 MB, while attachment and administration pages report 1 GB as the default and a configurable maximum of 2 GB per file. These should not be treated as a universal limit. Check the limit configured for your site and consult your administrator or the relevant Jira help page before changing or compressing evidence. Review attachment settings. Review the add-content guidance.

The administration documentation lists Jira Free storage as 2 GB per app, Standard as up to 250 GB per app, and Premium as unlimited. Plan details can change; confirm the current details for your site before using them for capacity planning. See Atlassian’s storage and attachment documentation.

Copied images between fields

Copying or pasting an image between multi-line fields can create a soft link to the original attachment. If the original is removed, the copied occurrence may become unavailable. Atlassian documents copying the image itself to create a duplicate attachment as a workaround. See Atlassian’s image-copy guidance.

7. Troubleshoot common Jira screenshot problems

Symptom	Likely cause	What to do
There is no attachment control	Attachments may be disabled, the user may lack Create Attachments permission, or the Attachment field may be hidden for that work type.	Ask a Jira administrator to check the attachment setting, permission scheme, and field configuration.
Upload is rejected	The file may exceed the limit configured for the site, or attachment settings may restrict uploading.	Check the applicable site limit with the administrator. If appropriate, reduce the image file size and upload again.
The image preview is unavailable	An external image source may be inaccessible, or the image may not have been uploaded as an issue attachment.	Upload the image directly to the Jira work item using its attachment feature, then reopen the work item and check the preview.
A copied image disappears after the original is removed	The copied occurrence may be a soft link to the original attachment.	Copy the image itself so Jira uploads a separate attachment, then verify the new attachment.
Reviewers cannot see the evidence	They may not have access to the work item or attachment.	Confirm the intended reviewers can access the Jira work item and its attachments under your site’s permissions.
Controls differ from instructions	The Jira work-item experience and labels may vary during the interface rollout.	Look for the attachment or Add control available in your site, or use drag-and-drop where supported.

Or skip the browser setup

If you need a screenshot of a page for a Jira report, ScreenshotNeo is a website screenshot API and MCP server. One GET request can return a PNG, JPEG, WebP, or PDF. The API also supports full-page capture, CSS selectors, custom CSS and JavaScript, viewport and device options, waits, cookies and headers, and more; see the ScreenshotNeo API documentation for the available parameters.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

Cookie and consent banners are accepted and removed before the shot, along with known newsletter popups and chat widgets; each cleanup step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers identify the page verdict and billing status. Its MCP server lets AI agents use screenshot, page-info, and PDF-capture tools. The free plan includes 1,000 screenshots a month without a card; paid plans start at $5 for 3,000 shots. Attach the resulting image to Jira so evidence remains with the work item.

Create a free ScreenshotNeo account for 1,000 screenshots a month with no card.

Performance, reliability, and cost notes

For Jira evidence, keep the capture focused on the state needed to explain the defect and use a recording only when motion matters. Direct Jira attachments avoid dependence on an external image host, but they use the site’s configured attachment and storage capacity. The documented per-file limits conflict across Jira help pages, so check your site setting before establishing a team-wide capture size target. ScreenshotNeo offers caching with a chosen TTL and bills only clean shots; its free and paid plan limits are listed above. No capture-time or throughput benchmark is asserted here.

FAQ

Should I report a visual bug with only a screenshot?

No. Include enough context and ordered steps for a teammate to reproduce the issue, and state actual and expected results separately.

Can I use a link to an image instead of uploading it?

A link can fail when the external image or its permissions change. Upload the screenshot to the Jira work item so it is stored with the report.

What attachment size should I assume in Jira Cloud?

There is no safe universal figure in the cited help pages because they conflict. Check your site’s configured limit with the Jira administrator.

When is a recording better than a screenshot?

Use a short recording as supporting evidence when timing or motion is central to the defect and your team’s policy permits it.