Why does my itch.io web game freeze without any error?

Because web games run in an iframe and unhandled errors land silently in the browser console that no player opens, leaving a frozen canvas. Hook the global error and unhandled-rejection handlers to capture these failures as reports, so the frozen canvas a player abandoned becomes a stack trace you can see.

What is WebGL context loss and how do I handle it?

The browser can revoke your WebGL graphics context at any time under GPU pressure or when a tab is backgrounded, freezing a game that does not handle it. Listen for the context-lost and context-restored events, implement context restoration, and capture context loss as a reported error so you know how often it happens across browsers.

What context should I capture from a web game crash?

Capture the browser and version, operating system, device type, screen size, and available memory, plus the error message and a stack trace made readable with source maps. Failures cluster by browser and device, and memory data helps you tell a logic crash apart from an out-of-memory tab reload.

Crash Reporting for Web Games on itch.io

Quick answer: Capture JavaScript errors, unhandled promise rejections, and WebGL context loss from your web game, with the browser, OS, and memory context attached. HTML5 games on itch.io run in a constrained iframe and fail silently, so global error capture is the only way to see what players hit.

A web game on itch.io is the easiest thing in the world to ship and one of the hardest to debug in the wild. It runs inside an iframe, in a browser you do not control, on hardware you cannot see, subject to memory limits and a graphics context that can vanish at any moment. When it breaks, the player sees a frozen canvas or a blank rectangle and closes the tab, and you never hear a word. Capturing JavaScript errors and the browser context is the only way to know what is actually happening inside that iframe.

Why web games fail silently

When a native game crashes, the operating system usually makes some noise. When a web game throws an unhandled error, it lands quietly in the browser console that no player ever opens, and the game simply stops. The player sees a stuck canvas, assumes the game is broken, and leaves. There is no dialog, no prompt, and no report unless you create one.

This silence is the core problem with web game distribution. Your itch page might be getting plenty of plays, but if a fraction of them hit an error and bail, you have no visibility into it at all. Global error capture turns those silent failures into reports, so the frozen canvas a player abandoned becomes a stack trace in your dashboard.

Capture JavaScript errors and rejections

The foundation is hooking the global error handlers. Listen for uncaught errors and for unhandled promise rejections, which are easy to miss because async failures do not always surface as a normal error. Together these catch the overwhelming majority of script-level failures in a web game, whether your game is plain JavaScript, compiled from another language, or running on WebAssembly.

Capture the error message, the stack trace, and the source location. For games compiled to WebAssembly or minified JavaScript, you will need source maps or symbol information to make the stack trace readable, just as native shipping builds need symbols. Keep that mapping for each build so a captured error points at real code, not minified gibberish.

WebGL context loss is a web-specific killer

A failure mode unique to web games is WebGL context loss. The browser can take away your graphics context at any time, when the GPU is under pressure, when the tab is backgrounded too long, when a driver hiccups, and if your game does not handle the context-lost event, it freezes or crashes. This is one of the most common web game failures and one players can never describe.

Listen for the context-lost and context-restored events and capture context loss as a reported error with the browser and device info. Knowing that a freeze was caused by context loss rather than a logic bug completely changes your fix, and seeing how often it happens across browsers tells you whether you need to implement proper context restoration as a priority.

Capture browser and memory context

Web games run across a huge matrix of browsers, versions, operating systems, and devices, and failures cluster along those lines. Capture the browser and version, the operating system, the device type, the screen size, and available memory where the browser exposes it. A crash that only happens on one browser or only on mobile is immediately more diagnosable when that dimension is attached.

Memory is a frequent silent killer in the browser, especially on mobile, where the tab has a tight memory budget and the browser will kill or reload a page that exceeds it. Capturing memory pressure when you can helps you distinguish a logic crash from an out-of-memory reload, which look identical to the player but need completely different fixes.

Setting it up with Bugnet

Bugnet provides a web SDK that hooks the global error and promise-rejection handlers and captures WebGL context loss, attaching browser, OS, device, and memory context automatically. You add it to your itch.io HTML5 build and errors start flowing into your dashboard, even from inside the iframe.

Add custom fields for your game state, like the current level or scene, and group identical errors into occurrence counts. Because the free tier covers a meaningful volume of reports, even a popular itch.io web game fits comfortably, and you finally get to see the silent failures that were quietly costing you plays the whole time.

Test across the browser matrix

Error capture tells you what broke, but a little proactive testing across browsers catches the worst issues before players do. Test your itch.io embed in at least Chrome, Firefox, and Safari, and on a mobile browser, because audio autoplay rules, WebGL support, and memory limits differ enough between them to break a build that runs perfectly in your development browser.

Beyond that, let the captured data guide your effort. You cannot test every browser and device combination, so your players collectively exercise the matrix, and their error reports tell you which combinations actually fail. A web game on itch.io that captures its errors stops being a black box and becomes something you can steadily make more reliable across the messy reality of the open web.

Inside the iframe, every failure is silent. Capture the errors or stay blind.