Process/Bug Reports/Triaging Playbook

Blender Bug Triaging Playbook

This document should be all someone needs to triage reports. If you encounter a situation that is not clear what to do, then is probably a new scenario.


Priority Clarifications
  • Unbreak Now! - Leave for module owners, but contact the responsible person on blender.chat if you think you found one.
  • Confirmed, High - Most crashes, recent regressions, or bug in a new feature.
  • Confirmed, Medium - Regular valid bug.
  • Confirmed, Low - Small annoyance in obscure workflows.
  • Normal - Not a bug, reserved for design documents, todos, and other generic tasks.


Missing Scenarios:

Add them here if you want them discussed before we create an action template for them.

  • None so far

Spam Scenario:

  • Task is spam

Should Close Task Scenarios:

  • Low quality report
  • Too complex file report, where user could not simplify enough
  • Feature request
  • Accidental feature request
  • Multi-report (many reports in a single report)
  • Valid report, but fixed already
  • Complete report, but out of memory
  • Complete report, but performance

Need More Information Scenarios:

  • Unexpected UI/Tool behaviour
  • Complete report, but cannot reproduce

Valid Bug Reports:

  • Valid report general instructions
  • Valid crash report, can confirm
  • Valid crash report, can confirm it crashes "at random"
  • Valid generic report, can confirm, known working version

Spam Scenario

Task is spam

Example: T70290

Action: Close the report as Invalid. Retitle report to "Removed spam", and empty the description and subscribers. Notify Nathan Letwory (@jesterKing) in blender.chat with link to the bug report for further action regarding user account.

Should Close Task Scenarios

Low quality report

Example: T56805, T69448

Action: Close the report as Archived explaining that report doesn’t contain enough information.


Message Example

This report does not contain all the requested information, which is required for us to investigate the issue.

Please submit a new report and carefully follow the instructions. Be sure to provide system information, Blender version, and a .blend file with exact steps to reproduce the problem.


Too complex file report, where user could not simplify enough

Example: T69566

Note: Python code is prone to introduce errors, so we are more strict on drawing the line for simplification in these cases.

Action: Close the report as Archived explaining our limitations in tackle complex files.


Message Example

Thanks for the report. Unfortunately the scenario described is too time consuming for us to track down, we require the bug reporter to narrow down the problem.

Normally .blend files can be simplified by removing most objects and disabling settings, until the problem reveals itself more clearly.

If there are many steps to reproduce the problem, please attach a .blend file saved right before the bug occures, so only a few steps are needed to trigger the bug.


Feature request

Example: T69676

Action: Close the report as Archived directing the user to the proper place for feature requests.


Message Example

Thanks for the report, but please use other channels for user feedback and feature requests: https://wiki.blender.org/wiki/Communication/Contact#User_Feedback_and_Requests

For more information on why this isn't considered a bug, visit: https://wiki.blender.org/wiki/Reference/Not_a_bug


Accidental feature request

Example: T66861

Note 1: Users may use tools for purposes they weren’t originally intended to solve and find they behave poorly. Even though it may seem like a bug. If they are trying to use functionality in a way it’s not intended - then it’s not considered a bug.

Note 2: If this seems like a generally useful improvement, we can consider adding it as a TODO as long as a developer has time to work on this. See: T63725

Action: Close the report as Archived explaining that we do only bugs here.


Message Example

Thanks for the report, but the issue reported here is a request for modified/improved behavior and not a bug in current behavior. Closing as this bug tracker is only for bugs and errors.

For user requests and feedback, please use other channels: https://wiki.blender.org/wiki/Communication/Contact#User_Feedback_and_Requests

For more information on why this isn't considered a bug, visit: https://wiki.blender.org/wiki/Reference/Not_a_bug


Request for support

Action: Close the report as Archived.


Message Example

For help using Blender, please try one of the community websites: https://www.blender.org/community/

If you think you found a bug, please submit a new report and carefully follow the instructions. Be sure to provide system information, Blender version, and a .blend file with exact steps to reproduce the problem.


Multi-report

Example: T39616

Action: Close the report as Archived, with a reply that users may edit to only include a single issue, opening new reports for all other issues.


Message Example

Thanks for the report. However to properly track issues we need them to be reported separately.

Please submit a new report for every individual bug.


Valid report, but fixed already

Example: T69806

Note 1: To be sure of this you need to have tested with both the reported blender, and the latest.

Note 2: If you don't have the blender used, and cannot reproduce the crash in any old version DO NOT close this report, refer to the "Complete report, but cannot reproduce".

Action: Close as Resolved, be explicit on the versions used to test and ask users to download a new blender.


Message Example

I reproduced this bug in the latest official release, but not the latest daily build, so it appears the bug has been fixed already.

Please try the latest daily build: https://builder.blender.org/download/

If the problem persists, please let us know so we can re-open the report. Don't forget to mention the specific version you tested again.


Complete report, but out of memory

Example: T69415

Action: Close as Archived and explain that the user needs more memory for production scenes.


Message Example

Thanks for the report. It appears this crashes because Blender ran out of memory.

While we want to improve Blender to handle such cases memory gracefully, this is not currently considered a bug.


Complete report, but performance

Example: T59438

Action: Close as Archived, unless is a lag with decent hardware, recent drivers and not-so-insane geometry/shader.


Message Example

Thanks for the report. While we do continue to work on improving performance in general, potential performance improvements are not handled as bug reports.

To improve performance, consider using less complex geometry, simpler shaders and smaller textures.


Unsupported graphics card or driver

Action: Close as Archived.


Old driver

Thanks for the report. The graphics driver version is too old. Please upgrade to the latest driver, see here for more information: https://docs.blender.org/manual/en/dev/troubleshooting/gpu/index.html


Unsupported graphics card

Thanks for the report. This GPU is below the minimum requirements for Blender, so we no longer provide support for it. https://www.blender.org/download/requirements/

Installing the latest graphics driver sometimes helps to make such GPUs work, see here for more information. https://docs.blender.org/manual/en/dev/troubleshooting/gpu/index.html

If that doesn't help, you can use Blender 2.79: https://www.blender.org/download/previous-versions/


Need More Information Scenarios

Unexpected UI/Tool behaviour

Example: T68798

Action: Put on Needs Information from User priority


Message Example

Please try with File → Defaults → Load Factory Settings to see if you still can reproduce this issue.


Complete report, but cannot reproduce

Example: T69415

Note: Assumes triager tested both the latest stable Blender and the latest HEAD.

Actions:

  • Set Needs Information from User priority.
  • If user was not using the latest stable or a recent nightly build blender and ask for they to test with recent Blender;
  • Otherwise ask for more clear instructions.


Message Example

I cannot reproduce this with either the latest stable or current development versions of Blender:

Please try the latest daily build: https://builder.blender.org/download/

  • Go to File → Defaults → Load Factory Settings and then load your file to see if you still can reproduce this issue.

If the problem persists, please give us more clear instructions on how to reproduce it from scratch.


Valid Bug Reports

Even valid confirmed reports can benefit from asking extra assistance from the reporter. In these cases (proven the files are not over complex) we can still go ahead and set their priorities.

Some of these topics have Advanced actions instructions. To follow these we presume the triager is already capable of building blender in release or debug modes.

Valid report general instructions

Action:

  • Tag it to the corresponding module tag.
  • Check if the title is good otherwise edit it.
  • Set priority to one of the confirmed ones.
  • If the file is complex enough that a developer would need to spend time further simplifying it, ask user to help.


Message Example

Thanks for the report, I can confirm the issue. The sample file could still be simplified further. Could you find a way to nail it down to a face with one material, simplified ui, …?


Valid crash report, can confirm

Example: T69810, T68586

Note 1: Set priority as Confirmed, High unless it is a really obscure bug. If you think it should be Unbreak Now! contact the corresponding module developers or one of our coordinators.

Advanced Action: If possible also include a one line crash message with a full backtrace stored in https://developer.blender.org/paste (see example tasks).


Message Example

Note for developers:

BLI_assert failed: //source/blender/blenkernel/intern/object_update.c:429, BKE_object_eval_eval_base_flags(), at 'base_index < MEM_allocN_len(view_layer->object_bases_array) / sizeof(Base *)

Full backtrace: P1097


Valid crash report, can confirm it crashes "at random"

Example: T66862, T67093

Note: We need first to determine if it is a thread "run condition" or memory access issue.

Action: Run Blender with --debug-depsgraph-no-threads --threads 1 to see if crash still happens (can use a regular release Blender)


Message Example

Thanks for the report.

Note for developers: I can confirm the issue with a regular Blender, but if I run it without threads (--debug-depsgraph-no-threads --threads 1) the issue goes away.


Advanced Action: Build a debug Blender with CMAKE_BUILD_TYPE=Debug WITH_COMPILER_ASAN=ON and WITH_ASSERT_ABORT=ON. If that still failed to catch the issue rebuild without the ASAN option, but with WITH_MEM_VALGRIND=ON instead. Include a one line error message with a full backtrace stored in https://developer.blender.org/paste (see example tasks).


Message Example

SUMMARY: AddressSanitizer: heap-use-after-free //source/blender/editors/transform/transform_conversions.c:3669 in flushTransUVs

Full backtrace: P1039


Valid generic report, can confirm, known working version

Example: T54121

Action: If the issue was introduced between the previous stable release and master this is a regression so its priority should be Confirmed, High.

Advanced Action: If triager has the time, or user volunteers to help, give general bisect instructions. After bisect update the task description with the known problematic issue.


Message Example

Thanks for helping us looking into that. If you want to help further and you already know how to build a debug version of Blender, you can find the exact commit that caused this problem by:

  1. Try building blender with master, to make sure you have all the requirements to build blender The problem (bug) should be present in this build.
  2. Try building blender with version de7a8af79380 [known working version]. The problem (bug) should not be present in this build.
  3. Do a bisect with:

git bisect start

git bisect bad HEAD

git bisect good de7a8af79380

It usually anywhere from 7 to 10 steps. Which means you will need to build Blender approximately 10 times until you get the culprit. For questions and assistance with that, check #blender-coders on blender.chat and point anyone to this reply.