Crash Reporting for Unity WebGL Builds

A Unity WebGL build is not a native game running in a browser, it is your game compiled to WebAssembly and run inside the browser sandbox, with a fixed memory heap, no file system, and all the constraints of the web. It fails in ways your native builds never do: out-of-memory errors when the heap fills, browser-specific WebGL issues, and silent JavaScript errors. Setting up crash reporting for a Unity WebGL build means capturing both the Unity-level exceptions and the underlying browser errors, with the memory and browser context that web failures demand.

WebGL is the browser, not native

When you build a Unity game for WebGL, the engine compiles your C# through IL2CPP to WebAssembly, which runs inside the browser. This means your game inherits every constraint of the web: a fixed memory heap allocated at startup, no direct file system access, the browser sandbox, and the variability of running across different browsers and devices. A WebGL build behaves quite differently from the same game built natively.

The consequence is that WebGL builds fail in web-specific ways. The most common is running out of memory, since the WebAssembly heap is fixed and a game that uses too much memory crashes when the heap fills. Browser differences, WebGL context loss, and the silent nature of web errors all add to the failure modes. Understanding that a WebGL build is a browser application, not a native one, is the foundation for capturing its crashes, because the failures are web failures and need web-aware capture.

Capture both Unity and JavaScript errors

A Unity WebGL build has two error layers. Your C# code raises Unity exceptions, which you can catch through Unity log and exception handling, and these carry your familiar stack traces. But beneath that, the WebAssembly runtime and the surrounding JavaScript can produce errors that do not surface as clean Unity exceptions, an out-of-memory abort, a JavaScript error in the loader, a WebGL failure, and these need to be caught at the browser level.

Capture both layers: hook Unity exception handling for the C# errors, and hook the browser global error handlers for the JavaScript and WebAssembly-level failures that the Unity layer does not see. The out-of-memory aborts in particular often surface as a JavaScript-level error or an Emscripten abort rather than a Unity exception, so capturing only the Unity layer misses them. Covering both the Unity and the browser error layers is what gives you complete crash visibility for a WebGL build.

Watch memory and the heap

Memory is the defining concern of Unity WebGL, because the WebAssembly heap is a fixed size set at build time, and when your game tries to allocate beyond it, the build crashes with an out-of-memory error. This is the single most common WebGL crash, and it is invisible in native builds where memory grows dynamically. Capturing the memory state at crash time is therefore essential.

Capture the configured heap size and the memory usage at the time of a crash, so you can see whether a crash is an out-of-memory failure, which they very often are. A crash that occurs as memory approaches the heap limit is an out-of-memory crash, and the fix is to reduce your memory footprint or increase the heap, which is a different response than a logic bug. Recording the heap size and memory usage on every crash lets you identify the out-of-memory crashes that dominate WebGL failures and distinguish them from genuine logic errors.

Capture the browser context

Like any web game, a Unity WebGL build runs across a wide range of browsers, devices, and operating systems, and crashes cluster along those lines. Capture the browser and version, the operating system, the device type, and whether the player is on mobile, since WebGL crashes can be browser-specific or hit memory limits harder on mobile, where the available heap is smaller and the constraints tighter.

Mobile browsers deserve particular attention, since a Unity WebGL build that runs comfortably on desktop can exceed the memory budget on a mobile browser, where the heap and the device memory are far more constrained. Capturing whether the crash came from a mobile browser, and the browser identity, lets you see when a crash is specific to a browser or to the tighter mobile environment. The browser and device context is what lets you cluster WebGL crashes and find the environment-specific failures across the messy reality of the web.

Setting it up with Bugnet

Bugnet captures Unity WebGL crashes at both layers, hooking Unity exception handling for C# errors and the browser global error handlers for the JavaScript and WebAssembly failures including out-of-memory aborts, with the browser, device, heap size, and memory context attached. Reports flow into one dashboard, so you see your WebGL build crashes alongside your other platforms.

Add custom fields for your game state, like the current scene, and group identical crashes into occurrence counts. Because WebGL crashes are dominated by memory and browser-specific issues, the captured heap-and-browser context is especially valuable: it lets you see whether your top crash is an out-of-memory failure that needs a smaller footprint, or a browser-specific issue that needs a compatibility fix, which completely changes how you address it across the web audience your WebGL build reaches.

Test across browsers and watch memory budgets

Crash capture covers the unknowns, but test your WebGL build across browsers, Chrome, Firefox, Safari, and a mobile browser, before launch, since browser-specific WebGL issues and the tighter mobile memory budgets show up quickly when you actually run the build in each. The memory issues especially reveal themselves when you test on a memory-constrained mobile browser rather than only on a desktop with abundant memory.

Set your heap size deliberately and test against it, since too small a heap causes frequent out-of-memory crashes while too large a heap fails to allocate on constrained devices, and finding the right budget requires testing on the devices and browsers your players use. Pair that testing with your captured crash data, which reveals the memory and browser issues across the full range of player environments you cannot all test. Together they let you ship a Unity WebGL build that holds up across the browsers and memory constraints of the web, which is where WebGL builds most often fall down.

A Unity WebGL build is a browser app with a fixed heap. Capture both error layers, the memory, and the browser.