Heuristic:ARISE Initiative Robosuite Numba BSOD Workaround
| Knowledge Sources | |
|---|---|
| Domains | Debugging, Robotics_Simulation |
| Last Updated | 2026-02-15 07:00 GMT |
Overview
Numba JIT compilation causes deterministic crashes (BSOD on Windows, black screen of death) for specific tasks when combined with offscreen rendering; disable via `macros.ENABLE_NUMBA = False`.
Description
Robosuite uses Numba's JIT compiler (`@numba.jit(nopython=True)`) to accelerate performance-critical numerical functions, particularly in `transform_utils.py` for matrix operations like `mat2quat`. However, Numba has a known interaction issue with MuJoCo's offscreen rendering that causes deterministic crashes. The NutAssembly task triggers a Blue Screen of Death (BSOD) on Windows, and the `tune_camera.py` script produces a black screen of death specifically during `mat2pose` -> `mat2quat` calls. The Numba JIT decorator is controlled by the `ENABLE_NUMBA` macro flag, which defaults to `True`.
Usage
Use this heuristic when:
- Encountering unexplained crashes or black screens during offscreen rendering
- Running the NutAssembly environment with offscreen rendering enabled
- Using the `tune_camera.py` or `tune_joints.py` scripts
- Debugging rendering issues that produce blank or corrupted frames
The Insight (Rule of Thumb)
- Action: Set `macros.ENABLE_NUMBA = False` in your `macros_private.py` or script if you encounter BSOD or black screen during offscreen rendering.
- Value: Boolean flag toggle: `ENABLE_NUMBA = False`
- Trade-off: Disabling Numba removes JIT compilation for transform functions, resulting in slower pure-Python execution of matrix operations. The performance impact is modest since these are small matrix computations, not batch operations.
- Scope: The known crash is deterministic and task-specific (NutAssembly offscreen rendering triggers it reliably).
Reasoning
The root cause appears to be a conflict between Numba's compiled code and MuJoCo's OpenGL rendering context. The crash path involves Numba-compiled `mat2quat` being called during the rendering pipeline. Since Numba generates machine code that may interact poorly with the OpenGL state, and MuJoCo's offscreen rendering uses platform-specific GL contexts (EGL/CGL/WGL), certain execution paths trigger undefined behavior.
The `jit_decorator` in `robosuite/utils/numba.py` provides a clean toggle mechanism:
Code evidence from `robosuite/macros.py:19-21`:
# TODO: Numba causes BSOD for NutAssembly task when rendering offscreen (deterministically!)
ENABLE_NUMBA = True
CACHE_NUMBA = True
Code evidence from `robosuite/utils/numba.py:9-12`:
def jit_decorator(func):
if macros.ENABLE_NUMBA:
return numba.jit(nopython=True, cache=macros.CACHE_NUMBA)(func)
return func
The `CACHE_NUMBA` flag controls whether Numba caches compiled functions to disk, which avoids recompilation overhead on subsequent runs.