Bug reports help modders fix issues and improve their mods. Whether your game crashes, an item behaves incorrectly, or something just seems off, reporting the issue properly ensures it gets fixed faster. This guide explains how to write an effective bug report.
As a mod developer I always appreciate when people report bugs. It’s a sign that not only are people playing the mod, but that they want it to be improved. While bugs are bad, it’s encouraging that people want to see the mod get even better.
Where Do I Report a Bug?
Most mods will have a preferred bug-reporting location, usually a GitHub Issues page or a dedicated Discord server. Check the mod’s description or documentation for details. Comments on mod pages are fine for small issues, but structured issue trackers make it easier for modders to track and fix bugs.
For example, clicking on the Issues link for Bok’s Banging Butterflies will lead to the GitHub Issues Page for the project, where you are free to submit your own bugs and suggestions for the mod.
What Information To Include
There are a few things to consider when writing a bug report. You don’t need to include all of the information listed below, but the more you do include, the faster a bug can be found and fixed.
Basic Information
Your report should start with a short, clear title that summarizes the issue. Examples of good titles include:
- Bottled Butterflies Not Dropping
- Butterflies failing to spawn in modded biomes
- Caterpillars Get Stuck When Pathfinding
A short but clear title helps modders quickly understand the problem before reading the details.
It’s also worth writing a short description as well. When you do so you should ask yourself two questions:
- What did you expect to happen?
- What actually happened?
An example of a good description might be:
I broke a butterfly jar and expected it to drop as an item. Instead it didn’t drop any items at all and has now disappeared from my world.
Now as a modder I know both what you wanted to happen, and what actually happened.
Version
Different Minecraft versions and mod loaders (Forge, Fabric, etc.) can cause different behaviors, so including this info helps pinpoint compatibility issues faster. So, if nothing else, include this information.
The version of Minecraft you are playing, the version of the mod, the launcher you are using, and whether or not you are playing on a server. This can be absolutely vital in tracking down a bug, since all of these things can influence what causes an issue. Often a bug only appears in one specific version and it saves a lot of time not having to test every single one.
All you need is a simple line stating something like:
Version: Minecraft 1.20.4, Forge, Mod v6.1.0
Including a quick description like this saves a LOT of time.
Reproduction Steps
This isn’t always necessary, but it can help the modder reproduce your bug if it’s a slightly more complex issue. Basically you just need to list the steps that can trigger the bug. Try to include steps starting from loading into a world, up until the bug occurs. It’s also important to mention the game mode (e.g. Survival or Creative), as this can affect what happens.
A good example of reproduction steps can be:
- Load any world with the mod installed
- Acquire a butterfly jar
- Place the butterfly jar in the world
- Make sure you are in Survival
- Break the butterfly jar
- Butterfly jar doesn’t drop
This gives instructions from the very beginning (loading into a game) to the point that the bug occurs. Reproduction steps can be important, since a modder may not be able to reproduce your bug, meaning they cannot fix it. It can also give them clues into the way people interact with the mod – they might need to update the mod to reflect how people actually use it.
Logs
Logs are always useful to modders. Often they can look at a log and instantly come up with a theory on how to test and fix a bug. To find a log you can look in your Minecraft installation folder (Open Folder option in CurseForge), and look under the /logs/ folder.
Usually you just want the latest.log file, but if the bug occurred on a specific date you can also include the gzip files. I haven’t found the files under /telemetry/ to be useful for debugging issues yet, but they may be useful for some issues.
If you’re unsure which part of the logs are relevant, don’t paste them directly into the bug report. Instead, upload the full file to Pastebin or Github Gist and share the link in the bug description. This makes it easier for modders to analyze the issue.
Crash Reports
If your game crashed then Minecraft will generate a crash report. These are found under the /crash-reports/ folder. Including these with your bug report is probably the most useful thing you can do if your game crashes, since it can point the modder to the specific line of code that caused the crash.
Just like the logs, you can use Pastebin or Github Gist to upload the full report.
Mod List
If you suspect it may be an interaction with another mod causing a bug then you should mention the other mod(s) in your description. Even if you don’t, it’s often useful to include a mod list as the modder can then spot something you may have missed.
If using CurseForge, you can export your modpack settings or check the mods folder for a list. Then you can use Pastebin or Github Gist similar to how you would submit a log or crash report.
Screenshots/Videos
While not always required, screenshots or short videos can be very helpful in identifying visual bugs or unexpected interactions. A screenshot of something wrong, or a video showing a bug can both be invaluable in allowing a modder to reproduce a bug.
Often players/testers will not include a step or a detail because it doesn’t occur to them that it’s important, but with an image or a video the modder can still spot this detail and be better clued in to the problem at hand.
Examples
What follows are a couple of examples of bug reports, both good and bad.
Bad Bug Report
“Your mod is broken. The game crashed.”
This is the worst kind of bug report. No information is given other than the fact that the game crashed. Even a small description of when the game crashed and which version would improve this bug report as it would give clues to the mod developer. An improvement could be as simple as:
“The game crashed when I loaded into a world using Neoforge 1.20.4 and the latest mod version.”
With this we have a reproduction and a version to help track down the bug. Whilst this is an improvement, it still isn’t the best bug report. An example of a much better bug report follows.
Good Bug Report
Title: Butterflies fail to spawn in modded biomes
Version: Minecraft 1.20.4, Forge, Mod v6.1.0
Description: Expected butterflies to spawn in my modded biome (Biomes O’ Plenty), but they don’t appear even after waiting several in-game days.
Steps to Reproduce:
- Load Minecraft with Bok’s Banging Butterflies and Biomes O’ Plenty installed
- Create a new world in Survival
- Travel to a Mystic Grove biome
- Wait multiple in-game days
- No butterflies spawn
This is a great example of a bug report. It has a specific version numbers, lists a potential mod compatibility issue, and says what was expected and what actually happened. It also includes clear reproduction steps.
The only improvement would be to include a log. Whenever possible, always include logs or crash reports, even if the bug seems simple. They can provide crucial information that isn’t obvious from just a description. Even if there’s no visible error, logs can still show hidden problems – so it’s always good to include them!
Conclusion
A well-written bug report speeds up fixes and improves the mod for everyone. Even a small report can lead to big fixes, so don’t hesitate to report anything odd!
Every bug report, big or small, helps make the mod better. Even if you only provide basic details, I appreciate every report and will do my best to fix issues quickly. If I need more info, I’ll ask; but the more details you include, the faster I can get the bug fixed!
