Crash Reporting for three.js and WebGL Games

three.js and raw WebGL bring real-time 3D to the browser, and that ambition comes with a distinctive set of failures. Beyond the silent JavaScript errors that affect any web game, 3D in the browser stresses the GPU hard, making WebGL context loss common, and depends on shaders that can fail to compile on specific hardware. A 3D web game can freeze on a black canvas for reasons rooted in the graphics layer that no player can describe. Setting up crash reporting means capturing the graphics context, context loss, GPU, shaders, that 3D web failures demand.

3D in the browser is demanding

A three.js or WebGL game pushes the browser graphics capabilities far harder than a typical 2D web game, rendering 3D scenes through the GPU in real time. This demand makes 3D web games more prone to graphics-specific failures: WebGL context loss when the GPU is under pressure, shader compilation issues on particular hardware, and out-of-memory situations from large textures and geometry. These are on top of the ordinary JavaScript errors any web game faces.

Because these failures are in the graphics layer, they are exactly the kind a player cannot describe, they see a black canvas or a frozen scene and leave. Capturing the graphics context, what the GPU is, whether the context was lost, whether a shader failed, is what turns these undescribable 3D failures into diagnosable reports. A WebGL game needs graphics-aware crash reporting, not just generic JavaScript error capture.

Capture JavaScript errors first

The foundation, as with any web game, is capturing JavaScript errors and unhandled promise rejections at the window level, since three.js and your game logic are JavaScript and most failures surface as JavaScript errors. Capture the message, stack trace, and source location, with source maps to make minified production traces readable.

This base layer catches the logic errors, the bugs in your game code and in how you use three.js. Capturing the active scene or game state alongside the error localizes it to a part of your game. But for a 3D web game, this JavaScript capture is necessary and not sufficient, because the most distinctive failures are in the graphics layer below your JavaScript, which the error handlers alone do not capture, and which you must address specifically.

Capture WebGL context loss

WebGL context loss is the signature failure of demanding web 3D. The browser can revoke the WebGL context at any time, under GPU pressure, when a tab is backgrounded, when the system is stressed, and a three.js game that does not handle the context-lost event freezes on a black canvas. This is one of the most common and most invisible WebGL game failures.

Listen for the WebGL context-lost and context-restored events and capture context loss as a reported event with the GPU and browser context, and implement proper context restoration so the game can recover. Knowing that a freeze was caused by context loss rather than a logic bug completely changes the fix, and seeing how often context loss happens across your players tells you whether handling it is an urgent priority, which for a GPU-intensive 3D web game it usually is.

Capture the GPU and shader context

3D failures cluster by GPU, because shaders and rendering features behave differently across graphics hardware and drivers. Capture the GPU renderer information that WebGL exposes, along with the browser and whether WebGL2 is available, so you can see which hardware a crash affects. A rendering crash that concentrates on one GPU family is a hardware or driver issue you can target.

Shader compilation is a specific 3D failure to capture: a shader that compiles on your development GPU may fail on a player different hardware, producing a black screen or a crash. Capture shader-compilation failures with the GPU context, so you can see which shaders fail on which hardware. The GPU and shader context is what makes 3D web crashes, which are fundamentally about the graphics hardware, diagnosable across the diverse GPUs your players bring.

Setting it up with Bugnet

Bugnet web SDK captures JavaScript errors and rejections with browser and device context, and you add WebGL context-loss capture and the GPU renderer and shader context as custom fields, so your three.js or WebGL game crashes arrive with the graphics context that 3D web failures demand. Everything flows into one dashboard with the browser and GPU context attached.

Group reports into occurrence counts and break them down by GPU and browser to find the hardware-specific rendering issues, and track context loss frequency as a health signal. Because 3D web games fail in the graphics layer that generic error capture misses, this graphics-aware reporting is what lets you see and fix the context-loss, shader, and GPU crashes that were freezing players on black canvases and silently costing you the audience your demanding 3D web game worked hard to attract.

Test across GPUs and handle degradation

Because 3D web crashes cluster by GPU, test your game across different graphics hardware where you can, including integrated graphics and a range of GPUs, since a shader or rendering feature that works on your development GPU may fail elsewhere. Mobile GPUs especially differ from desktop, and a 3D web game that targets mobile browsers faces both weaker GPUs and tighter memory.

Beyond catching crashes, design for graceful degradation: handle context loss with restoration, provide fallbacks for unsupported features, and scale down for weaker GPUs, so the game degrades rather than crashing on hardware that cannot handle the full experience. Combined with your GPU-tagged crash data, which tells you which hardware actually fails, this lets a demanding 3D web game reach the widest possible audience across the diverse graphics hardware of the open web, rather than crashing on everything below your development machine.

3D web games break in the GPU layer no player can see. Capture context loss, the GPU, and the shaders.