How-To: Write Better Bug Reports

[kouyo]

A well-written report is important, it will help us to understand, reproduce and fix the issue as quickly as possible. Please follow these guidelines below before submitting your report. At the end of this guide, you’ll find a template that you can copy and use for your submission.

1. Write a clear title​

Make the title specific and descriptive. Use the appropriate keyword to describe where the issue occurs. Some examples:

• [Mainsite] — Issues on the main website.
• [Forum] — Issues on the forums.
• [Reader] — Issue with the reader.
• [PWA] — Issues on the PWA (Progressive Web App) version of MangaDex.
• [Uploader] — Issues during chapter uploads or with the upload page.
• [Editor] — Issues when editing data.
• [API] — Issues with the MangaDex API.

Those are some examples, please use any other you find best for describing for your issue.

Examples:

[Mainsite] Homepage doesn't load in Safari on macOS 15

2. Describe the issue​

Explain the problem in detail. Try to answer at least the following questions:

• What’s happening?
• What should be happening?
• When did the issue start?
• Does it happen every time or only sometimes?
• Did you see any error message?
• Does the issue persist if you go into incognito/private browsing mode?
• Do you have any extensions running on your browser?

Example:

"When I try to load the site in Safari, I get a "Safari can't open page" error and the page doesn’t load. It should load normally, like it does in Chrome and Firefox. The site worked fine before. The issue happens every time I try to open the page in Safari. It persists even in private browsing mode. I have a few extensions (ad blockers, password manager), but disabling them didn’t resolve the issue."

3. Include steps to reproduce​

Provide clear steps to reproduce the issue. This will helps us investigate. Include URLs and any relevant actions (for example if the bug occurs when a certain button is clicked or when you do a specific set of actions).

Example steps:

• Open Safari 18 on macOS 15.
• Go to https://mangadex.org
• Notice the page fails to load and shows a "Safari can't open page" error.

4. Provide environment details​

This is even more useful for us, being able to reproduce the bug in a nearly similar environment will help us to identify the problem easier.

Include information like:

• Browser (and version)
• Operating system (and version)
• Device
• Any special conditions (Wi-Fi vs. mobile data, etc.)

Example:

• Browser: Safari 18
• OS: macOS 15
• Device: MacBook Air
• Network: Wi-Fi (same issue on mobile data)

5. Additional information​

If possible, include:

• Screenshots or screen recordings
• Error messages from your browser console
• Network request data (e.g., if an API request fails)

Example:

Screenshot of the error message, console logs showing a 404 error, and network request data failed with a 403 forbidden error.

6. Provide extra context (Optional)​

This can help the developers narrow down the potential cause. If relevant, add:

• Links to related issues or similar bugs
• Mention if the issue started after a specific update

Example:

"It seems like this bug started happening after the update on November 16th when the homepage layout was updated."

---

​

Bug report template​

Title:
(Should go on the thread title)

Description:
(Brief description of the issue)

Steps to Reproduce:
1.
2.
3.
(Add more steps if needed)

Environment Details:

• Browser:
• Operating System:
• Device:

(Add any other detail if needed)

Additional Information:
(Screenshots, screen recordings, error messages, console logs, etc.)

Additional Context:
(Related issues, mention if the issue began after a certain update, etc.)