Sponsored By

Featured Blog | This community-written post highlights the best of what the game industry has to offer. Read more like it on the Game Developer Blogs.

How To Report Bugs

Handling bugs in a proper way is essential for game quality. In this post I'll present a clear and effective method to report bugs.

Leszek Gorniak, Blogger

June 22, 2018

6 Min Read

Cave Troll cannot be defeated with some weapons.

HUD displays incorrect amount of ammo.

Graphics in level 3 is broken.

Each of the above statements describes a potential bug in your game. However, none of them provide information required by programmers or designers to fix the issue. Those are, of course, a bit exaggerated examples. Nevertheless, I’ve seen way too many imprecise, incomplete and even incomprehensible bug reports, both as a QA specialist in the IT industry and as a developer and designer in the game industry.

In this post, I’d like to present a bug report template that is, in my opinion, clear, effective and sufficient. Here it is:

  • Title

  • Category

  • Severity/Priority

  • Steps to Reproduce

  • Current Result

  • Expected Result

  • Affected Version

  • Reproducibility

  • Platform

  • Attachments

There are two important remarks before I move on. Firstly, reporting bugs is all about communicating all that’s required to fix a bug, and nothing more. The main purpose of the above template is to provide such information. However, note that not every bug report must include all points.

Secondly, using some sort of a bug tracking tool is more than advisable. In case of very small projects, Google Docs could be a sufficient solution, but for more complex projects you’re going to need a tool that enables you to categorize, prioritize and filter bugs. I personally recommend Mantis for small and medium projects (10-30 people) and JIRA for big projects (30+ people). Keeping reported issues in order should be considered the first step towards fixing them.


The title should be short and descriptive. Graphics in level 3 is broken surely is short, but not really descriptive. Skyscrapers in level 3 don’t have materials applied sounds better, and in this particular case the title alone might provide enough information to fix the bug (unless not all skyscrapers are affected).


Each bug’s occurrence can be narrowed down to a specific game project area: User Interface, Audio, Dialogues, AI, etc. Such a category should be included in the bug report, as it helps to filter out a specific type of issue and points to a person/team to which a given bug should be assigned.


Severity describes how “harmful” a bug is. Slightly displaced UI button is a Minor issue, while a crash that prevents a player from completing the main quest is a Blocker. 

Priority is in many cases directly proportional to Severity. Bug tracking tools usually have a separate drop-down menus for Severity (e.g. Minor, Major, Critical, Blocker) and Priority (e.g. Low, Normal, High, Urgent).

Steps To Reproduce

This is the most important part. Without a detailed step-by-step instruction on how to reproduce a bug the person responsible for fixing it won’t able to do it or will spend too much time and effort investigating how to reproduce the issue. Listed steps should be as detailed as needed (knowing what’s needed comes with experience) but also as simple as possible. I’ll give some examples later on.

Current Result

Basically, this should answer the question “What happens after I perform all steps listed in the previous part (Steps to Reproduce)?” Bear in mind that sometimes a single screenshot or error log says more than a hundred words (see Attachments part).

Expected Result

This one is not always required, but in some cases the report is incomplete without indicating what actually should happen in a correct scenario (if there was no bug).

Affected Version

If you found a bug in a specific build that has a version number or code, this code should be included in the report.


This indicates whether a bug always occurs when Steps to Reproduce are performed or whether it’s not recurrent or in some way difficult to track. In a perfect situation, before reporting a bug we should always come up with such Steps to Reproduce that always result in the bug, but in some cases it will not be possible (for example bugs connected with low performance are sometimes difficult to reproduce).


Not always required, but sometimes necessary. Examples:

  • game is developed for e. g. PC, PS4 and XBox, and the bug occurs only on one of those platforms

  • the bug is related to low performance, so we need to report an exact hardware configuration

  • game is developed for web browsers, and the bug occurs only in a specific browser


Those could be:

  • screenshots (very useful when describing bugs related to environments and UI)

  • videos (could illustrate some strange AI behaviors)

  • error logs (in case of any kind of crashes they should be considered a complementary part of the report)

OK, let’s see how the bug descriptions listed at the beginning could look like with the bug template applied.

Example 1: Cave Troll cannot be defeated with some weapons.

Title: Great Axe doesn’t do any damage to Cave Troll
Category: Gameplay
Severity/Priority: Critical/High
Steps to Reproduce

  1. Prerequisites: Act 2 should be active

  2. Travel to the Dwarven Realms

  3. Talk to Ghotrek to activate the Cave Troll side-quest

  4. Go to the Cave Troll’s lair

  5. Equip any weapon of Great Axe type

  6. Attack and try to damage the Cave Troll

Current Result: Cave Troll receives no damage
Expected Result: <rather obvious, so can be omitted>
Affected Version: 0.3.1
Reproducibility: always
Platform: any
Attachments: N/A

Example 2: HUD displays incorrect amount of ammo.

Title: Too much ammo is added after reload
Category: UI/HUD
Severity/Priority: Major/High
Steps to Reproduce: 

  1. Equip any firearm (let’s assume it has 30 bullets in the clip)

  2. Fire 5 bullets

  3. Reload

Current Result: HUD displays 55 bullets loaded (amount before reload + clip size)
Expected Result: HUD should display 30 bullets loaded (amount before reload + 5 after the reload)
Affected Version: 0.3.1
Reproducibility: always
Platform: any
Attachments: screenshot with incorrect value marked on HUD

Example 3: Graphics in level 3 is broken.

Title: Skyscrapers in level 3 don’t have materials applied
Category: Environments
Severity/Priority: Minor/Normal
Steps to Reproduce: <can be omitted, as the title is descriptive enough>
Current Result: please see attached screenshot
Expected Result: <rather obvious, so can be omitted>
Affected Version: 0.5b
Reproducibility: always
Platform: PS4
Attachments: screenshot with Skyscrapers

Handling bugs in an organized and consistent manner is essential for game quality. Using a clear and unified bug report template will boost your communication and team performance and, in the end, help deliver a smooth game experience that the players expect.

Thank you for reading.

Read more about:

Featured Blogs
Daily news, dev blogs, and stories from Game Developer straight to your inbox

You May Also Like