Bug report form — capture reproducible reports that engineers can actually fix

Who this template is for

Bug-report forms are the form most product teams ship with the wrong fields. The typical version asks for "what happened" and "contact email," produces a vague text report with no environment context, and routes to a generic support inbox where someone has to manually re-enter the data into Linear, Jira, or GitHub Issues — losing fidelity and adding hours of back-and-forth to extract the information engineering actually needs. The right version captures four things that turn a vague report into an actionable engineering ticket: a clear description of what happened (the symptom the user observed), structured steps to reproduce (the single highest-value field — bugs that can't be reproduced typically can't be fixed), expected versus actual behavior (the diff that defines the bug), and the auto-captured environment metadata (browser + version, OS + version, device class, app version or build, URL where it happened, user agent, timezone) that eliminates the "can you tell me what browser you're using" follow-up that delays most fixes. Severity self-assessment is captured but treated as a user-impact signal rather than an internal-priority signal — users self-report at higher severities than engineering would assign (everyone's bug feels critical to them), so the right pattern is to capture impact signals (couldn't complete checkout / lost work / cosmetic issue / wrong number displayed) and let engineering triage convert to internal severity. The form integrates with the engineering team's actual tracker — Linear, Jira, GitHub Issues, Asana, Trello, Notion, ClickUp, or the Sentry / Bugsnag / Rollbar / Embrace stack when the report comes from a crash event — so the bug appears as a properly-structured ticket without manual re-entry. Use this template instead of the generic support form and the time-to-fix for the bugs that matter measurably improves.

From bug report to engineering ticket in under 60 seconds

A user encounters a bug — wrong behavior, error message, broken feature, crashed action — and triggers the bug-report form (via in-app "report a bug" link, support widget, or dedicated page). The form loads with the environment metadata already captured silently: browser name and version, OS and version, device class, app version or build number, current URL, user agent, timezone, and (when integrated with crash reporting) the most recent crash report if the bug followed a crash. The user describes what happened in plain language, provides structured steps to reproduce ("1. Go to /settings, 2. Click 'change password,' 3. Enter new password, 4. Click save, 5. Error appears"), notes what they expected vs. what actually happened, attaches a screenshot or screen recording (optional but heavily encouraged — a 10-second video of a misbehaving UI is worth more than three paragraphs of description), self-reports impact level (can't complete a task / lost work / cosmetic issue / wrong information displayed / other), and provides contact for follow-up. On submission, the form fires a webhook to the engineering team's tracker of choice — Linear (modern team default, creates an issue with structured fields), Jira (enterprise standard with custom-field mapping), GitHub Issues (open-source and dev-tool convention with labels and assignees), Asana / Trello / Notion / ClickUp for lighter setups, Sentry / Bugsnag / Rollbar / Embrace when the bug intersects with crash reporting. The auto-captured environment data populates the ticket's environment fields automatically. The user receives a confirmation with the ticket reference number, the expected follow-up SLA, and a status link they can check. The whole flow takes under 60 seconds for the user and produces a ticket the engineering team can triage and act on without back-and-forth.

What's included

Each field below is here because experienced engineering teams have learned what's needed for a bug to actually get fixed quickly. The auto-captured environment metadata is the differentiator — manually-collected versions of these fields produce missing or wrong values 30-50% of the time; auto-captured versions are correct.

Built for the product categories where bug-fix velocity directly affects retention

• B2B SaaS (the primary use case)

  The category where bug-fix velocity most directly affects customer trust. B2B SaaS bug reports range from cosmetic (logo misaligned on dashboard) to revenue-blocking (customers can't sign up, can't pay, can't access core feature). The structured form routes the latter to engineering's high-priority queue with all the context needed for immediate investigation. Notion, Linear, Figma, Stripe, Vercel, Datadog, PostHog, Snowflake, MongoDB Atlas all run variants. The integration pattern: bug report → Linear (or Jira for enterprise) issue with structured environment data → engineering triage assigns severity and owner → fix lands → user notified via the contact captured in the form. For Brazilian B2B SaaS (RD Station, Pipefy, Conta Azul, Bling, Omie, Movidesk, Octadesk, ContaWise), the same pattern applies with locale-specific considerations: bugs in the Pix integration, NFSe issuance, Boleto generation, fiscal-compliance flows are typically high-severity because they block billable revenue and can trigger Receita Federal compliance issues.

• Developer tools (devs report bugs in their own language)

  Different vocabulary, similar structure. Developer-tool bug reports tend to be technically detailed by default — devs include stack traces, error messages, console output, and reproduction steps with more rigor than other audiences. The form for dev tools can be lighter on fields because the audience self-provides detail, but the auto-captured environment metadata still helps because devs forget to mention browser version, Node version, framework version. Vercel, Stripe, Twilio, Datadog, PostHog, Linear, Sentry, Bugsnag, Anthropic Claude API, OpenAI API, GitHub Copilot all run bug-intake variants. For modern AI-developer tools (Cursor, Windsurf, Continue, Cline, Aider, Anthropic Claude Code), bug reports often include the prompt context (what the user asked, what the model responded, what went wrong) — this category should capture the prompt-context field explicitly because debugging AI behavior without the prompt is impossible. For Brazilian developer tools, the GitHub Issues integration is the canonical destination because most Brazilian open-source projects and Brazilian dev-tool startups run on GitHub.

• Mobile apps (more detail than the mobile-app-feedback's unhappy route)

  Mobile bug reports differ from desktop in three ways: the auto-captured metadata is richer (device model, iOS or Android version, app build number, network type, battery state, memory available — all auto-captureable on mobile platforms), the reproduction steps often involve specific gestures (swipe, pinch, long-press) that text descriptions handle poorly, and crash context from Crashlytics / Sentry / Bugsnag / Instabug / Embrace can auto-attach when the bug followed a crash. The form for mobile should encourage video upload (a 15-second screen recording of the buggy behavior is the highest-signal asset a mobile bug report can include) and integrate with the crash-reporting stack for crash-adjacent bugs. For Brazilian mobile apps (Nubank, iFood, Mercado Pago, Magalu, PicPay, BTG digital), bug-report integration with Reclame Aqui pre-resolution workflow is increasingly standard — capturing user dissatisfaction in-app via bug report and resolving it before the user posts publicly preserves the Reclame Aqui score that materially affects Brazilian consumer trust.

• E-commerce (checkout bugs are critical revenue blockers)

  Bug-report routing in e-commerce has a specific dynamic: revenue-blocking bugs (checkout fails, payment doesn't process, product page doesn't load, search broken) need to route to engineering's high-priority queue immediately with revenue-impact context attached. The form should auto-capture cart context (which products, which payment method attempted, which step of checkout failed) when the bug is reported from a checkout-related page. For Brazilian e-commerce (MercadoLivre, Magalu, Americanas, Shopee Brasil, AliExpress Brasil, Shein Brasil), checkout bugs around Pix integration, parcelamento calculation, NFSe issuance for marketplace sellers, and Reclame Aqui status updating are particularly common and particularly high-impact. For Spanish e-commerce (El Corte Inglés, Carrefour España, Wallapop, Vinted), bugs around Bizum integration, SEPA Direct Debit, and EU VAT calculation are similarly high-impact.

• Gaming (bug reports tied to live ops and player progression)

  Game bug reports have specific patterns: lost-progress bugs (game state corruption, lost purchases, lost in-game currency — which spawn refund requests and customer escalations to Apple/Google support), balance bugs (a weapon or character does the wrong damage, a level is impossible to complete), live-ops bugs (the new event mode doesn't work, the limited-time offer doesn't apply), and platform-integration bugs (Steam achievements not unlocking, PlayStation trophies not registering, Xbox Live not syncing). The auto-captured metadata for game bug reports should include game version, platform, region, account ID (for the engineering team to look up the specific player state), and session context. For Brazilian gaming specifically (Garena Free Fire dominant in Brazil, Mobile Legends, Clash Royale, EA FC Mobile, Brawl Stars with large Brazilian user bases), bug reports in Portuguese with translated severity descriptions and Brazilian time-zone context are non-optional for fast triage.

• Hardware and IoT (firmware bugs, sensor issues, connectivity)

  Hardware bug reports have unique constraints: the device might be the source of the bug (a sensor reading wrong, an actuator not responding, a firmware regression after update), the connectivity layer might be the issue (Wi-Fi pairing failures, Bluetooth disconnects, cloud sync issues), or the companion app might be the issue (visualization wrong, settings not syncing). The auto-captured metadata for hardware bug reports needs to span both the device (firmware version, hardware model, sensor data at the time of the report) and the connected app (app version, mobile OS, network type). Examples: Tesla bug reports through their in-car interface, smart-home devices (Nest, Ecobee, Philips Hue), connected fitness (Peloton, Tonal), smart-watch and wearable (Apple Watch, Fitbit, Garmin, Oura). For Brazilian and Spanish-speaking hardware product audiences, the documentation and bug-report flow in the user's native language reduces the friction of reporting hardware issues that the user is already frustrated about.

Configure the form to your tracker and your bug-triage workflow

Start with the integration target. Linear is the modern team default for issue creation — the bug-report webhook creates a Linear issue with environment data in structured fields, the title from the user's symptom description, the description from the steps-to-reproduce, and labels for severity and area. Jira is the enterprise standard with similar capability and more configuration overhead. GitHub Issues is the convention for open-source projects and dev-tool startups. Asana, Trello, Notion, ClickUp work for lighter teams. For crash-adjacent bugs (the user reports the bug after a crash), integrate with Sentry, Bugsnag, Rollbar, Embrace, Firebase Crashlytics so the crash context auto-attaches to the bug report. Capture the steps-to-reproduce field as required text (not optional) because the bug-fix velocity directly depends on whether engineering can reproduce the bug — submissions without reproduction steps generate hours of back-and-forth that good auto-capture eliminates. Make the screenshot/video upload prominent but optional — most users will upload if asked, and visual evidence is dramatically higher-signal than text descriptions. Capture impact-level signals (couldn't complete task / lost work / cosmetic issue / wrong data displayed) as the user-side signal, but let engineering convert to internal severity (P0/P1/P2/P3) during triage — user self-assessment of severity is unreliable. For multi-product companies, route bug reports by area (which product/feature/page) so the right engineering team picks up the ticket without manual rerouting. For Brazilian brands, integrate with Reclame Aqui pre-resolution workflow when applicable. Translate the form into the languages of your users — bug reports in the user's native language reduce ambiguity and improve triage speed.

Bug report form FAQ

Related templates