How to File a Browser Bug

As you build and debug more websites and web applications, eventually you’ll come upon an issue that is not a bug in your code, but a but in the code for a browser itself. Fortunately, most major browsers support bug reporting by developers, and provide public access to the state of each reported bug. To play a constructive role in the process:

  1. Do your research first. Any bug you find has likely already been reported by another developer.
  2. Follow bug reporting guidelines. For your bug report to be helpful, it’s important that you provide all the information necessary for browser makers to recreate and fix your bug.

More details below the fold.

Almost every time I debug HTML, CSS, or JavaScript code, I learn something about the web that I didn’t know before — be it specifications, best practices, or simply workarounds. But occasionally, I’ll chase down a maddening bug that makes no sense and eventually recognize that the bug is not in my code, but in the browser I’m testing on. Because browsers are themselves pieces of software, the code used to create them is prone to bugs, just like any code that you or I write.

Do your research first

If you think you’ve found a browser bug, the best place to start is a good web search. Try to find descriptions of the same issue by other developers, especially on reliable websites such as Most often when I think I’ve found a browser bug, it’s actually an intentional behavior based on the browser maker’s interpretation of web standards such as the WHATWG HTML Living Standard.

In addition, you may find that your issue turns up in the bug tracker for that browser maker. This means it is a bug that’s already been reported. These bug trackers generally allow you to create an account and mark an issue as something that you’d like to see fixed. This can serve as an informal ranking system to help the engineers who work on the browser to prioritize which bugs to fix. It can also allow you to receive updates of progress on the bugs you’re interested in. Chrome, Firefox, and Edge all have public bug trackers:

In addition, you can report Safari bugs using the Apple bug reporter, which requires signing up for an account.

Follow bug reporting guidelines

If you don’t find the issue you’re experiencing after search the web, you may indeed be experiencing a bug that hasn’t yet been reported. If you get to this point, you should file a bug report to let the engineers working on that browser know what you’re experiencing, and to give them the opportunity to try to recreate what you’re seeing.

Each bug reporting system has its own list of requested information. However, bug reports should generally include the following:

  • System details: your operating system version and browser version.
  • What you did: the specific, reproducible steps you took that caused the issue; any engineer should be able to follow these steps on a system matching your system details and see the results you’re reporting, as well as try the steps in a newer version of the browser to test if the issue is fixed.
  • What you expected would happen: a description of the behavior that you thought should result from what you did.
  • What happened instead: a description of the erroneous behavior you experienced, including the specific text of any error messages (with screenshots if possible).

You can examine the public bug tracker for any major browser for examples of bug reports that follow this pattern.

You should also be sure to subscribe to updates on any bugs you report. Engineers assigned to your bugs may have additional questions, or may be able to point you to other resources that shed light on your issue. They generally do this using the bug tracker so the conversation is available to anyone with an interest in the product.

By reporting only issues that you’ve researched and that have a high likelihood of being browser bugs, and by filing useful reports, you help make the web better for everyone, and strengthen skills that can make you an asset on any team.