--- title: "Bug report template (copy and paste) for web apps" description: "A free bug report template for web apps: title, steps, expected vs actual, environment, console and network. Copy it as Markdown, or record it in one click." canonical: https://faylee.app/docs/guides/bug-report-template --- # Bug report template (copy and paste) for web apps A good bug report lets someone else reproduce the bug without asking you anything. The template below covers what a developer needs to do that for a web app. Copy it into your issue tracker, a chat message or a document, and fill in each field. ## Quick version (5 fields) ```markdown ## Title [Where] [what goes wrong] [when] ## Steps to reproduce 1. 2. 3. ## Expected result What should have happened. ## Actual result What happened instead. ## Environment URL, browser, operating system ``` Use this for small bugs; use the full template below when the bug is intermittent, affects money or data, or comes from a customer. ## The template ```markdown ## Title [Where] [what goes wrong] [when] ## Summary One or two sentences on what is broken and who it affects. ## Steps to reproduce 1. 2. 3. ## Expected result What should have happened. ## Actual result What happened instead. Quote any error message exactly. ## Environment - URL: - Browser and version: - Operating system: - Screen or window size: - Account or role: ## Frequency Always / Sometimes / Once ## Console errors Paste the red lines from the browser console, with their stack. ## Failed network requests - Method and URL: - Status: - Response body: ## Screenshot or recording Link: ## Severity and impact Who is blocked, and is there a workaround? ``` ## Before you file: three quick checks - **Search the tracker first.** If someone has already reported the bug, add your steps, environment and evidence to that report rather than filing a duplicate. - **One bug per report.** Separate bugs get fixed and closed separately, so two problems in one report means one of them gets lost. - **Try a private window with extensions off.** An incognito or private window rules out cache, cookies and browser extensions as the cause. ## How to fill in each field **Title.** Say where the bug is, what goes wrong and when. A developer should know which part of the app to open from the title alone. - Bad: "Checkout broken" - Good: "Checkout: Pay button does nothing after applying a coupon" **Summary.** One or two sentences in plain words. Say who is affected if you know: every user, one account, only admins. **Steps to reproduce.** Number every step, starting from a page anyone can open. Include what you typed and what you clicked, in order. Leave nothing out because it seems obvious. - Bad: "Try to check out with a coupon, it fails." - Good: 1. Sign in as a customer and add any item to the cart. 2. Go to /checkout. 3. Enter the coupon `SPRING10` and click **Apply**. 4. Click **Pay**. **Expected result.** What the app should have done, such as "the payment form submits and the order confirmation opens". This stops a developer from fixing the wrong thing. **Actual result.** What you saw instead. Copy error messages word for word. "Nothing happens" is a useful answer when nothing happens. **Environment.** The page's full URL, the browser and its version (in Chrome, open `chrome://version`), the operating system, the window size, and the account or role you used. The free [browser and screen checker](https://faylee.app/tools/browser-info) copies the browser, system and sizes as one block. Many bugs only show for one browser, one screen size or one kind of account. **Frequency.** Always, sometimes or once. A bug that happens sometimes points to timing, caching or data, and the developer will look in different places. **Console errors.** The errors the page logged. These often name the cause directly. See [the two fields people skip](https://faylee.app/docs/guides/bug-report-template#the-two-fields-people-skip-console-and-network). **Failed network requests.** Requests that returned an error status or never finished. The method, URL, status and response body are usually enough to tell a frontend bug from a backend one. **Screenshot or recording.** A picture shows the state of the page. A video shows the order of events, which a picture can't. **Severity and impact.** Who is blocked and whether there is a workaround. This decides how soon it gets fixed, so be honest about it. ## A filled-in example This is an invented bug in an invented shop, to show the fields in use. ```markdown ## Title Checkout: Pay button does nothing after applying a coupon ## Summary After a valid coupon is applied, clicking Pay does nothing. Customers who use a coupon can't place an order. ## Steps to reproduce 1. Sign in as a customer and add any item to the cart. 2. Go to https://shop.example.com/checkout. 3. Enter the coupon SPRING10 and click Apply. The discount shows. 4. Click Pay. ## Expected result The payment is submitted and the order confirmation page opens. ## Actual result Nothing happens. The button stays enabled and no message appears. ## Environment - URL: https://shop.example.com/checkout - Browser and version: Chrome (latest stable) - Operating system: macOS - Screen or window size: 1440 × 900 - Account or role: customer account, no saved card ## Frequency Always, when a coupon is applied. Without a coupon, Pay works. ## Console errors Uncaught TypeError: Cannot read properties of undefined (reading 'amount') at submitPayment (checkout.js:212:31) ## Failed network requests - Method and URL: POST /api/orders - Status: 422 - Response body: {"error":"discount.amount is required"} ## Screenshot or recording Link: (recording of steps 1 to 4) ## Severity and impact High. Every order with a coupon fails. Workaround: remove the coupon. ``` With the console error and the failed request, a developer can start at `submitPayment` and the coupon payload instead of trying to reproduce the bug first. ## More bug report examples These are invented too, including every number in them. Each one shows a different kind of evidence doing the work. **A layout bug.** The window size and the fresh session are what make it reproducible. ```markdown ## Title Settings: Save button hidden behind cookie banner on 1366 × 768 ## Steps to reproduce 1. Open https://app.example.com/settings in a private window, so the cookie banner shows. 2. Change any field and scroll to the bottom. ## Expected result The Save button is visible and can be clicked. ## Actual result The cookie banner covers the Save button. Clicking it hits the banner instead. ## Environment - URL: https://app.example.com/settings - Browser: Chrome (latest stable), window 1366 × 768 - Operating system: Windows - Not seen at 1440 × 900 or wider, or after the banner is dismissed. ``` **A slow page.** The network timing shows where the time goes, so the developer starts on the server, not the page. ```markdown ## Title Reports page takes ~12 s to load for accounts with many projects ## Steps to reproduce 1. Sign in to an account with 200+ projects. 2. Open https://app.example.com/reports. ## Expected result The page loads in a second or two, as it does for small accounts. ## Actual result A spinner shows for about 12 seconds before the table appears. ## Network - GET /api/reports?include=projects: 200, 11.8 s total, 11.6 s waiting for the server, 4.2 MB response - Same request on an account with 3 projects: 200, 0.4 s ## Environment - Browser: Chrome (latest stable), Operating system: macOS - Frequency: Always, for large accounts ``` **A server error.** The method, URL, status and response body point straight at the backend. ```markdown ## Title Upload avatar: 500 error for PNG files over 2 MB ## Steps to reproduce 1. Go to https://app.example.com/profile. 2. Click Change avatar and choose a PNG file of 2.4 MB. ## Expected result The new avatar is saved and shown. ## Actual result "Something went wrong" appears and the old avatar stays. ## Failed network requests - Method and URL: POST /api/users/me/avatar - Status: 500 - Response body: {"error":"internal_error","request_id":"req_8f2c1a"} ## Notes A 1.8 MB PNG and a 3 MB JPEG both upload fine. Always happens. ``` ## The two fields people skip: console and network Most reports leave out the console and the network. They are the fields that save the most time, and the hardest ones for someone who isn't a developer to fill in. Asking a customer to "press F12 and open the Network tab" rarely works. ### Copy console errors in Chrome 1. On the page with the bug, press F12, or Ctrl+Shift+J (Cmd+Option+J on a Mac), to open DevTools on the **Console** tab. 2. Reproduce the bug with DevTools open. 3. Click the red error to expand its stack. 4. Select the error and its stack and copy them, or right-click in the console and choose **Save as…** to save the whole log as a file. ### Export network requests as a HAR file A HAR file holds every request the page made, with headers and bodies. 1. Open DevTools and go to the **Network** tab. 2. Tick **Preserve log**, so requests survive a page change. 3. Reproduce the bug. 4. Click the download arrow in the Network toolbar (**Export HAR**), or right-click a request and choose to save all as HAR, then attach the file to the report. See [What is a HAR file?](https://faylee.app/docs/guides/har-file.md) for every browser and how to clean one before sharing. :::caution A HAR file can contain cookies, authorization headers and whatever was typed into forms. Check what it holds before you attach it anywhere public. The [HAR file viewer](https://faylee.app/tools/har-viewer) shows every request in it without uploading the file. ::: ## The template in Jira, GitHub Issues and Linear The fields stay the same in every tool. Only where they go changes. **Jira.** Create an issue of type **Bug**. The title goes in **Summary**. Steps, expected, actual, console and network go in **Description**. Use the **Environment** field if your project has it, otherwise keep that section in the description. Set **Priority** from severity, and attach the screenshot, recording or HAR file. **GitHub Issues.** Paste the template as the issue body, which renders as Markdown, and add a `bug` label. To give everyone the same form, save it in your repository as `.github/ISSUE_TEMPLATE/bug_report.md` with a short header: ```markdown --- name: Bug report about: Something in the app doesn't work labels: bug --- ``` Then paste the template below the header. For a structured form instead of a Markdown body, use the [issue form](https://faylee.app/docs/guides/bug-report-template#github-issue-form-bug_reportyml) below. **Linear.** The title goes in the issue title and the rest in the description, which takes Markdown. Add a **Bug** label and set the priority from severity. Linear also has issue templates in the team's settings, where you can save this one. ## GitHub issue form (bug_report.yml) GitHub issue forms live at `.github/ISSUE_TEMPLATE/bug_report.yml`. Instead of a Markdown body to edit, reporters get a form with labelled fields, dropdowns and required answers, and GitHub turns their answers into the issue body. Save this file in your repository as it is, or trim the fields you don't need. ```yaml name: Bug report description: Something in the app doesn't work title: "[Bug]: " labels: ["bug"] body: - type: markdown attributes: value: | Thanks for reporting a bug. Please search existing issues first, and file one bug per report. - type: input id: summary attributes: label: Summary description: Where the bug is, what goes wrong and when. placeholder: "Checkout: Pay button does nothing after applying a coupon" validations: required: true - type: textarea id: steps attributes: label: Steps to reproduce description: Number every step, starting from a page anyone can open. value: | 1. 2. 3. validations: required: true - type: textarea id: expected attributes: label: Expected result description: What should have happened. validations: required: true - type: textarea id: actual attributes: label: Actual result description: What happened instead. Quote any error message exactly. validations: required: true - type: input id: url attributes: label: URL placeholder: https:// - type: dropdown id: browser attributes: label: Browser options: - Chrome - Edge - Firefox - Safari - Other - type: input id: os attributes: label: Operating system placeholder: macOS, Windows, Linux - type: dropdown id: frequency attributes: label: Frequency options: - Always - Sometimes - Once - type: textarea id: console attributes: label: Console errors description: Paste the red lines from the browser console, with their stack. render: shell - type: textarea id: network attributes: label: Failed network requests description: Method and URL, status, and response body. - type: input id: recording attributes: label: Screenshot or recording link - type: dropdown id: severity attributes: label: Severity description: Who is blocked, and is there a workaround? options: - Blocker (no workaround) - Major (workaround exists) - Minor (cosmetic or rare) ``` The browser dropdown is the reporter's browser. Add or remove options to match the browsers your app supports. ## Skip the template: record it instead The template asks a reporter to collect what the browser already knows. Faylee collects it for them. With [Faylee's Chrome extension](https://chromewebstore.google.com/detail/hlpfigkebjnklihappcmmjimjkmpmaif), which also works in Edge, Brave and Arc, you [record the tab or screen](https://faylee.app/docs/capture/recording.md) while you show the bug, or [save an instant replay](https://faylee.app/docs/capture/instant-replay.md) of the last few minutes after it already happened. One link then carries: - The video, or for an instant replay, a replay of the page. - The console, with errors and their stacks. - Every network request with its headers and bodies. - The steps to reproduce, from your clicks, typing and page changes. - The browser, system and window size. - A DOM replay of the page you can inspect at any moment. A developer opens the link in the web viewer and reads the [console and network](https://faylee.app/docs/viewer/devtools.md) next to the video. A coding agent such as Claude Code, Codex or Cursor can read the same report through Faylee's [MCP server](https://faylee.app/docs/agents/mcp.md) and work on the fix there. Customers who don't have the extension can send a screen recording through a [recording link](https://faylee.app/docs/support/recording-links.md), with no install. To try it, [start free](https://app.faylee.app/users/sign-up), or see [pricing](https://faylee.app/pricing). ## FAQ ### What should a bug report include? A clear title, numbered steps to reproduce, the expected and actual result, the environment (URL, browser, operating system, account), how often it happens, and any console errors and failed network requests. A screenshot or recording helps a developer see the order of events. ### What's the difference between a bug report and a feature request? A bug report says the app doesn't do what it is meant to do, and gives the steps to show it. A feature request asks for something the app was never meant to do. If you can't name an expected result the app is supposed to give, it is probably a feature request. ### How do I get console logs from a customer? You can walk them through opening DevTools and copying the errors, as in [the steps above](https://faylee.app/docs/guides/bug-report-template#copy-console-errors-in-chrome), though it often goes wrong. A browser extension that records the console with the bug does it without the customer touching DevTools. ### Can I attach a bug report to Jira or Linear? Yes. Paste the template into the issue, as above. Faylee also files reports as issues in Linear, GitHub, Jira, GitLab, Azure DevOps, ClickUp, Notion, Asana and Trello, with the steps, errors, failed requests and environment drafted from the capture, and keeps comments in step both ways with most of them. See [Integrations overview](https://faylee.app/docs/integrations/overview.md) and [Issue trackers](https://faylee.app/docs/integrations/issue-trackers.md).