Crash Reporting For Unity On WebGL itch.io Builds

Shipping a Unity game to itch.io as a WebGL build is the easiest way to get it in front of players, and the hardest place to know when it breaks. A WebGL build runs inside the player's browser as WebAssembly, where it can run out of memory, throw JavaScript exceptions, or fail to initialize inside itch's embedding, all without ever showing you a crash log. The player just sees a frozen canvas and closes the tab. This guide covers crash reporting for Unity WebGL on itch.io: the browser and WASM failure modes, why they are invisible by default, and how to capture them with enough context to fix.

Why WebGL crashes are uniquely invisible

On a desktop build, a Unity crash leaves a log file on the player's disk that you might eventually get your hands on. A WebGL build leaves nothing. It runs sandboxed inside the browser tab, and when it dies, the error vanishes into the browser console that the player never opens. There is no crash dump, no log directory, no stack trace waiting for you. The player sees a black or frozen canvas, assumes the game is broken, and leaves your itch page, taking the only evidence of the crash with them when they close the tab.

This invisibility is worse on itch.io specifically because of how casual the audience is. Itch players click in, expect the game to load in seconds, and bounce instantly if it does not. They will not file a bug report, hunt for your Discord, or open developer tools to copy an error. The crash that lost you that player is doubly hidden, both by the browser sandbox and by the low-commitment nature of the platform. Without deliberate crash reporting, your WebGL game can be failing for a large share of visitors while your itch analytics show only an unexplained bounce rate.

Memory is the number one killer

The most common way a Unity WebGL build dies is running out of memory. Browsers cap how much memory a WASM module can allocate, and Unity's heap, combined with your assets, can blow past that limit, especially on lower-end machines or memory-hungry tabs. The failure often looks like an out-of-memory abort or a generic WASM trap, and it tends to hit hardest exactly where you cannot reproduce it: on a player's modest laptop with twenty other tabs open, not on your development machine with everything to spare.

Because memory failures are environmental, they are nearly impossible to catch without capturing the real conditions players run in. The same build that never crashes for you aborts constantly for someone on a four-gigabyte Chromebook. To fix this you need crash reports that arrive with the browser, the device memory hints, and the point in the session where the allocation failed, so you can tell whether you are leaking, loading too much at once, or simply need to shrink your heap. Guessing at memory limits from your own machine is how WebGL games stay broken for the players who matter most.

JavaScript exceptions and the embedding layer

Beyond memory, WebGL builds fail at the seams between Unity and the browser. A JavaScript exception thrown in the loader, a missing data file, or a CORS issue can stop the game before Unity even starts, and these errors live in the browser's JavaScript layer rather than in your C# code. They are easy to miss because they do not look like Unity crashes at all; they look like a page that quietly failed to load, which on itch.io is indistinguishable from a player who simply left.

The itch.io embedding adds its own quirks. Your build runs inside an iframe with specific sizing, fullscreen, and storage behaviors, and the canvas can fail to size correctly, input can be captured by the wrong layer, or local storage can behave differently than it did when you tested the raw build locally. These embedding-specific failures only appear once the game is actually running inside itch's wrapper, which is exactly why testing the standalone build is not enough and why capturing errors from the real embedded context is essential to catching them.

Capturing the right context

A WebGL crash report is only useful if it carries the context that explains the failure. For these builds that means the browser and version, the operating system, a sense of available memory, the game build version, and the JavaScript error or WASM abort message with whatever stack is available. Browser and version alone often crack a case open, because a crash that only happens on one browser's WASM implementation or one mobile browser points you straight at the cause without any further detective work on your part.

Equally important is the build version, because itch.io makes it trivial to push frequent updates and equally easy to lose track of which build a given crash came from. Stamping each report with the build means you can confirm whether a memory fix actually reduced out-of-memory aborts in the new upload while the old build still shows them. Without that, you are flying blind across rapid itch updates, unable to tell whether your last change helped or whether the crash you thought you fixed is still hitting players on the current build.

Setting it up with Bugnet

Bugnet captures crashes from Unity WebGL builds at the browser layer, so JavaScript exceptions, WASM out-of-memory aborts, and loader failures are recorded even though the player never opens the console. Each report arrives with the browser, operating system, memory context, and your itch build version attached, plus whatever stack the browser exposes. Identical crashes group into one issue with an occurrence count, so a memory abort hitting many low-end visitors shows up as one ranked problem rather than vanishing into your itch bounce rate.

Because the build version rides along on every report, the rapid update cycle itch encourages stops working against you. Push a memory fix as a fresh upload and you can watch out-of-memory aborts fall to zero on the new build while the previous one still shows them, which is direct proof the change helped rather than a hopeful guess. Filtering by browser surfaces the failures confined to one engine's WASM implementation, the exact pattern that points straight at the cause. The frozen-canvas players who used to bounce in silence become a counted, diagnosable issue you can actually close.

A testing routine for itch builds

Build a small testing routine that respects how WebGL actually fails. Test the embedded itch build, not just the local one, across at least a couple of browsers and on a deliberately memory-constrained machine, because that is where your real audience's failures live. Watch your captured crashes after every upload, since itch's easy updating means you ship often and each upload can introduce or fix browser-specific issues. Treat the first hours after an upload as a window to catch a regression while only a few players have hit it.

Over time, captured crash data turns WebGL from a black box into a manageable platform. You learn which browsers your audience uses, where your memory ceiling really is, and which embedding quirks bite, and you can size your heap and assets accordingly. The itch.io players who used to bounce off a frozen canvas in silence become a counted, fixable issue at the top of your list. The whole point of crash reporting for WebGL is to make the platform's invisible failures visible, so you stop losing players you never even knew you had.

WebGL crashes vanish into the browser sandbox and your itch bounce rate. Capture them at the browser layer with build context so frozen-canvas players become fixable issues.