Creating bug reports for Discourse on Meta

:bookmark: This is a guide for reporting about bugs you find in Discourse using the correct channels.

:person_raising_hand: Required user level: Anyone can report bugs

When you encounter an issue that breaks or prevents the normal use of Discourse, it is crucial to report this bug so that it can be addressed and fixed. Reporting bugs helps improve the platform for everyone - this documentation will guide you through the process of reporting a bug effectively on Meta, an excellent way to contribute to Discourse.


In this guide, you will learn:

  • How to ensure the bug hasn’t already been resolved
  • How to validate the issue on the official Discourse testing environment
  • How to create a detailed bug report

Ensuring the bug isn’t already resolved

Before reporting a bug, search in the bug category on Meta for similar issues to make sure it has not already been reported. This helps avoid duplicate reports and provides insights into whether the bug has been acknowledged or fixed.

Validating the issue

To confirm that your issue is a reproducible bug and not specific to your setup:

  1. Test on Use the default sandbox at to see if you can replicate the problem.
  2. Use the Tests-Passed channel: If you’re testing on your own Discourse development instance, make sure to use the main release branch, also known as the Tests Passed channel.

Advanced steps (optional)

  • Submit a Pull Request: If you are capable, submit a pull request with a failing test that demonstrates the bug.
  • Fix the bug yourself: If you prefer to address the issue on your own, follow the Contributing to Discourse development.

Creating a detailed bug report

Finally, if the issue persists and you’ve confirmed it on the testing environment:

  1. Open a topic in the bug category: Go to the bug category on Meta and create a new topic.
  2. Include reproducible steps: Detail everything you know about the bug, including the steps to reproduce it. Refer to the guide on how to write a good bug report for tips on what information to include.

Once the bug is fixed, you can generally expect updates to be posted in the reporting topic.

Additional Resources

Last edited by @hugh 2024-06-12T09:54:09Z

Last checked by @hugh 2024-06-11T02:40:44Z

Check documentPerform check on document: