Which JavaScript handlers should I hook in a Construct 3 web export?

Hook window.onerror, or an error event listener, for synchronous uncaught exceptions, and unhandledrejection for promises that reject without a catch. Construct uses promises internally for loading and many plugin actions, so both are needed. Register them before the runtime boots so startup errors are not missed.

How do I connect a JavaScript stack trace back to my event sheets?

The stack references the exported runtime, not your events, so leave breadcrumbs. Use a script action or the browser plugin to log layout changes and major actions to a ring buffer, plus markers before fragile sequences, then attach the buffer to each report to identify the responsible event group.

Why do some crashes only happen in certain browsers?

Web exports inherit browser behavior around WebGL, storage, audio, and privacy settings, so Safari, Firefox, and embedded webviews differ. Capturing the user agent, WebGL availability, viewport size, and host URL lets you spot environment-specific failures that usually trace to an untested fallback path.

Crash Reporting for Construct 3 Web Games

Quick answer: Construct 3 exports your event sheets to JavaScript that runs in the player's browser, so crashes surface as window onerror and unhandledrejection events rather than engine dialogs. Hook those two browser handlers, capture the message, source, and stack, add the browser and device context Construct exposes, and submit each report so duplicates group and you can trace failures back to the event sheet behavior that caused them.

Construct 3 lets you build a whole game from event sheets without writing much JavaScript, but when you export to the web your game becomes ordinary browser JavaScript, and that is where crashes live. A player on an old mobile browser or a locked-down work laptop hits an error you never saw in the editor, and unless you are listening for it the game just freezes or goes blank. This post covers how Construct 3 web exports actually fail, which browser hooks catch those failures, and how to package each one so it points back at the event logic behind it.

How Construct 3 web games fail in the browser

When you export a Construct 3 project for the web, the runtime and your compiled event logic run as JavaScript inside the player's browser. Failures therefore look like browser failures: an uncaught TypeError when an instance was picked that no longer exists, a rejected promise from a fetch that loaded game data, or a WebGL context that the browser refused to create on weak hardware. None of these show an engine error box, because there is no engine process, only a tab that stops responding.

Because the game is sandboxed in a tab, you also inherit browser-specific behavior. Safari on older iPhones, Firefox with strict privacy settings, and embedded webviews inside portals like itch.io or Poki each behave slightly differently around storage, audio, and WebGL. A crash that only appears in one of these environments is common, so identifying the browser and host is as important as the error message itself.

The two browser hooks that catch almost everything

Two global handlers cover the vast majority of Construct 3 web crashes. window.onerror, or an addEventListener for the error event, fires on synchronous uncaught exceptions and gives you the message, source file, line, column, and an error object with a stack. window.addEventListener for unhandledrejection fires when a promise rejects without a catch, which matters because Construct uses promises internally for loading and for many plugin actions. Together they catch synchronous and asynchronous failures alike.

Register both as early as possible, ideally before the Construct runtime fully boots, so you do not miss an error during startup or first asset load. Keep the handlers tiny and synchronous in their critical path: record the data, hand it to your reporting layer, and return. Doing heavy work inside an error handler in a browser that is already struggling is a good way to turn a recoverable hiccup into a frozen tab.

Tying a browser error back to event sheets

The hardest part of Construct 3 debugging is that the JavaScript stack trace references the exported runtime, not your event sheet rows. To bridge that gap, leave breadcrumbs from inside your events. Use the browser plugin or a small script action to log layout changes, major game states, and the last few significant actions to an in-memory ring buffer. When an error fires, attach that buffer so the report reads like a short story ending in the crash.

You can also tag risky areas explicitly. Before a known-fragile sequence, such as a save, a leaderboard call, or a plugin that touches the network, write a marker breadcrumb. When a report arrives with that marker as its last entry, you instantly know which event group to inspect. This converts an opaque runtime stack into a guided path through your own logic, which is exactly what you need when you cannot set a breakpoint on a player's phone.

The context a web crash needs to be useful

A web crash report is only actionable if it carries the environment. Capture the user agent string, the browser name and version, the operating system, the screen and viewport size, the device pixel ratio, and whether the game is running fullscreen or embedded in an iframe. Add whether WebGL or WebGL2 was available, the renderer string, and the host page URL so you can tell an itch.io embed from a direct load. Construct exposes much of this through the platform and browser objects.

Layer your own game fields on top: build version, current layout, score or level, and any feature flags you toggle. With both halves present, a report stops being a bare stack and becomes a precise situation. You can see at a glance that a particular error only strikes WebGL-less Safari at small viewport sizes, which often points straight at a rendering fallback path you forgot to test on real hardware.

Setting it up with Bugnet

Bugnet gives you a small web SDK and an in-game report button you can drop into a Construct 3 export. Wire your onerror and unhandledrejection handlers to call the SDK, passing the message, stack, breadcrumb buffer, and the browser context, and each crash lands in one dashboard already enriched. The same report button lets a confused player send a manual report with a screenshot when the game merely misbehaves rather than crashes, so you catch the soft failures event handlers never see.

Occurrence grouping is decisive for web games because one popular browser quirk can generate thousands of identical errors in a day. Bugnet folds those into a single issue with a count, so instead of drowning you see one ranked list. Custom fields like browser, host page, and WebGL availability become filters, letting you confirm a spike is iframe-only or Safari-only and fix the matching event logic or fallback without guessing across a dozen environments.

Testing across the browsers that matter

Before each release, run your export through the browsers and hosts your players actually use: current Chrome and Firefox on desktop, Safari on a real iPhone, and at least one embedded portal frame. Deliberately throw a test error and reject a test promise to confirm both handlers still fire after a Construct runtime update, since exports change between editor versions and a silently broken handler is worse than none.

Once live data flows, work the occurrence list top down and watch counts drop after each fix. Web players almost never file a manual report, so this passive stream is often your only window into how the game behaves outside your editor. Treating it as a first-class signal rather than noise is what keeps a Construct 3 web game stable across the messy reality of the open browser.

Construct web games crash as browser JavaScript, so hook onerror and unhandledrejection, breadcrumb from your events, and attach browser context to make each report fixable.