How to report issues or suspected bugs
If you’ve found an issue, we’d love to hear about it! However, there are certain things required to document bugs so your report is meaningful to the development team. We accept bug reports in one of two ways: if you’re on the demo or Learning license, through this forum (and the user community), if you’re on a Base/Pro/Playback license, through our support form.
Think of a bug report as something that should be succinct, factual and to the point. It needs to include the following elements to be valuable:
- The version of Notch you are running
- A reproduction case — this will be a DFX that has any irrelevant nodes or content removed, showcasing only the buggy behaviour (more about this further down)
- Reproduction steps (a written description on how to reproduce the bug) — if we can’t reproduce it on our systems, we can’t track down the bug
- The expected result VS the actual result
- If it’s a visual bug: proof (screenshots/capture or a video)
Before you report an issue
The most important things to check before you report an issue:
- Make sure you’re running the latest version of Notch
- Check the forum or manual to see if you’re looking at something that has a common fix
- Make sure your issue involves hardware/software that we actually support
- Gather the information needed, and
- Write a reproduction case
What’s a good reproduction case?
Good reproduction steps can take time to write out clearly, simplify and verify. As someone who reports a bug to us, we expect you to shoulder as much of this burden as you can, making it easy for us to reproduce and resolve bugs. These steps are complete, self-contained (anyone on our team can reproduce the issue by opening the submitted DFX and following the steps) and easy to follow.
An example of a good report
Issue:
Cannot get the environment mapping node to affect connected 3D objects. The attached DFX has a simplified reproduction case (environment mapping node, camera, one light, two 3D objects to include/exclude).
Repro steps:
- Connecting the 3D Object to the “Objects” input on the environment mapping node
Expected result:
- The 3D Object should now display the attached environment map
Actual result:
- The 3D Object remains grey and is coloured only by the scene lights
An example of a bad report (one that will be ignored)
I can’t get the volumetric shadows to work. I have used the right kinds of settings according to the manual but it still doesn’t work. I’m on a deadline here, so please help me quickly ok?
We realize that this might sound harsh, but you’d be surprised at how many “bugs” are simply user errors or fundamental misunderstandings on how Notch or real-time graphics in general works. Of course, genuine bugs do definitely exist, and we want to know about them and fix them, but without a proper bug report, we can do neither. Help us help you, and submit proper bug reports. 
How do I simplify my issue report?
Great question, here are a few tips! In general, you’ll need to find a scenario where the issue is reliably reproducible (meaning: “always bugs out”) and one where nothing goes wrong. Once you have both cases (which can often be just the matter of adding or disconnecting a single node), you change the scenarios step-by-step to be as similar to each other as they can, until you have two scenarios which have as few nodes as possible but still don’t look or behave the same. The remaining difference usually points directly at the root cause.
For example, you have a problem with displaying an image using an Image 2D node.
- Did it work with a different image file?
- What’s different about the image file that works and the one that doesn’t work?
- Is the issue related to the file itself?
- If not: are you using the image files on the same Image 2D node?
- If used on different nodes, are they set up in the same manner?
- If different, what are the differences? What happens if you connect a working image to a working Image 2D node and switch between them?
Working through these steps might often help you discover the issue without reporting a bug altogether.
What if the issue isn’t reproducible?
In the rare cases where you experience an issue that you simply can’t build reproduction steps for, one which is only reproducible in your environment, or which you don’t want to narrow down to a minimal reproduction case, we cannot accept it as a bug report.
We simply do not have the resources to pursue reports with limited, inaccurate or incomplete reproduction steps, and therefore any bug report without them will be rejected. Such reports require a large amount of our time and are often fruitless to pursue.
If the issue is important to you but falls outside the scope of permissible bug reports, we sometimes offer tailored support at consulting rates. You can get in touch with us to inquire about such cases.
What happens when we reproduce your issue?
When you file a proper bug report, the absolute first thing we do is to assume nothing and instead try to reproduce it on our end. We do this by opening your submitted DFX and following the steps you provide us. If we can recreate the issue locally we can almost always figure out what the problem is and start working on a fix.
When is the fix available to me?
That depends on the severity of the issue, what the fix entails, how quick it is to correct, what other parts of the system a fix might affect, how far along we are in our next version release schedule and many other factors. Keep in mind that a seemingly simple fix still includes getting the fix (and others) through our extensive set of QA tests, so it might not be available to you immediately.
In the case that a bug is discovered which does not have an easy fix, we will always try to provide you with a workaround that fits your scenario so that you can keep working on your project.