[v3][Windows] WebView2 ProcessFailed is unhandled — browser-process death leaves the window permanently blank until app restart

[randalmurphal]

Description

Wails v3 on Windows never registers WebView2's ProcessFailed event. When the WebView2 browser process dies — for any reason — the controller is left in a permanently invalid state: every subsequent COM call returns ERROR_INVALID_STATE (0x8007139F), the window renders blank, and only restarting the host app recovers. The app process itself stays alive, so the user is left staring at a dead white/blank window with no indication of what happened.

Concrete triggers:

• The mixed-DPI GPU-kill loop in [v3][Windows] Mixed-DPI monitor drag kills WebView2 GPU process repeatedly until the browser process exits — window permanently blank #5732 (reproducible chain: degenerate transform → repeated GPU process kills → FATAL ... GPU process isn't usable. Goodbye. → browser process exits).
• Killing msedgewebview2.exe from Task Manager (trivial repro of the same end state).
• Any WebView2 runtime crash or out-of-resource kill.

Renderer-level failures (RENDER_PROCESS_EXITED / RENDER_PROCESS_UNRESPONSIVE) similarly leave a dead view where a simple re-navigation would recover.

Observable aftermath in a host log once the browser process is gone (every focus/resize event storms these):

[WebView2] Focus failed: The group or resource is not in the correct state to perform the requested operation.
[WebView2] SetSize failed: The group or resource is not in the correct state to perform the requested operation.

This is closely related to #5580's audit (transient COM errors exiting the process via errorCallback): alpha2.112 stopped the crash, but what remains is a window that can never recover. Handling ProcessFailed is the recovery half of that story.

Fix, validated

Branch: https://github.com/randalmurphal/wails/tree/fix/webview2-process-failed-recovery (single commit off the v3.0.0-alpha2.112 tag).

• Register chromium.ProcessFailedCallback in setupChromium.
• RENDER_PROCESS_EXITED / RENDER_PROCESS_UNRESPONSIVE → re-navigate to the last host-set URL (tracked in setURL; the dead webview can't be queried for it).
• BROWSER_PROCESS_EXITED → rebuild: fresh edge.NewChromium(), re-run setupChromium, re-navigate. The old instance is abandoned rather than re-embedded — after a browser-process exit all its COM references dangle, and Embed's init-wait loop keys on a per-instance flag a used instance has already set, so re-embedding would return before a new controller exists.
• GPU/utility process failures are deliberately left alone: Chromium restarts those itself, and if it gives up, that arrives as BROWSER_PROCESS_EXITED.
• Work is deferred out of the callback via InvokeAsync, per WebView2 guidance about not calling controller methods reentrantly from event handlers.

Validated on Windows 11 26200 / WebView2 149.0.4022.98: with the browser process dying mid-session, the window rebuilds and re-renders in ~1–2s instead of staying blank.

Design points where you may want something different — happy to adjust in a PR:

• In-page state is lost on rebuild (it's gone regardless; the question is whether recovery should be automatic).
• Auto-reload on RENDER_PROCESS_UNRESPONSIVE is opinionated — some apps may prefer waiting out a transient hang, so that case may want to be option-gated or surfaced as an event.
• There's currently no event surfaced to the app that a recovery happened; apps with meaningful frontend state may want a hook.

Happy to submit the branch as a PR if the approach looks right.

Environment

• Wails: v3.0.0-alpha2.112 (tagged)
• OS: Windows 11 Enterprise 25H2 (build 26200)
• WebView2 Runtime: 149.0.4022.98

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity.
It will be closed if no further activity occurs within the next 10 days.

If this issue is still relevant, please add a comment to keep it open.
Thank you for your contributions.

[leaanthony]

Thanks for this @randalmurphal 👍This issue flew under the radar so apologies for the slow response. There's a linked PR which is an extraction of the differences so far. Regarding your other points:

State is lost regardless. Not sure what we can do about that TBH.

Auto-reload on RENDER_PROCESS_UNRESPONSIVE is opinionated — some apps may prefer waiting out a transient hang, so that case may want to be option-gated or surfaced as an event.

There's currently no event surfaced to the app that a recovery happened; apps with meaningful frontend state may want a hook.

Agreed - Perhaps a policy plus a recovery time trigger. We could have a WebviewRecoveryCallback function pointer. when there's an issue, an event is fired saying it happened, then if this option is not nil we call it for manual handling. The signature will return the policy to either recover or not, perhaps through a boolean. User can determine if a delay is needed or not at that point?

[randalmurphal]

Quick status first: I ran #6002 through the full manual matrix on real Windows hardware and posted the results on the PR, with fixes for the issues found (#6002 (comment)).

Callback + event sounds right to me. A few suggestions from that validation work, for whatever they're worth:

Consider passing the failure kind and attempt number into the callback, so an app can treat a hung renderer differently from a dead browser process. For the delay, it may be safer as a return value (recover / ignore / recover after N) that wails schedules, rather than user code waiting inline: if the callback ends up invoked from the ProcessFailed handler, an inline wait would pump/block inside the event handler, which is the same docs prohibition that bit the rebuild path on #6002.

One docs detail worth designing around: for RENDER_PROCESS_UNRESPONSIVE the event "will run every few seconds until the process becomes responsive again", and there's no responsive-again signal. That's convenient for "wait it out" (a declining callback gets asked again), but repeated fires probably want to count as one episode for the attempt budget, in case a re-navigation doesn't clear the hang. Caveat: I haven't exercised the unresponsive path on hardware, this is from the docs. FWIW Microsoft's ProcessFailed sample recreates the webview for this kind rather than re-navigating.

On the event: for apps with meaningful frontend state the useful moment is "recovery finished, page reloaded", since that's when they can rehydrate. Maybe both: failure occurred (kind + attempt) and recovery succeeded/failed.

Happy to implement the callback + events on top of #6002 once it lands.