Handling process-related events in WebView2

  • Article

WebView2 uses multiple processes to support the WebView2 controls in your application. Because these processes can exit during use, WebView2 provides the CoreWebView2.ProcessFailed and CoreWebView2Environment.BrowserProcessExited events for your application to react to different scenarios. Use this document to learn how to use these events to react when these scenarios occur.

To improve the reliability of your WebView2 application, it is recommended that your app handles at least the following events:

To use this article, we recommend first reading Process model for WebView2 apps. For a list of process-related APIs covered by this article, see Process management in Overview of WebView2 features and APIs.

Events for processes that exited or failed

When you initialize a WebView2 control, WebView2 will ensure there's a WebView2 Runtime to power your control and connect to its WebView2 Process Group. Once this connection is established, your control will start monitoring these processes and report the following events so your application can react accordingly:

  • Any process failure. When any of the processes in the WebView2 Runtime fails, the CoreWebView2 will raise the ProcessFailed event. This can be due to a process crash, or an unresponsive renderer process. Use this event for diagnostics and recovery from failures in the WebView2 processes. See Handle process crashes and A process rendering content in the WebView2 control has exited unexpectedly, below.

  • Main browser process exits. If the main browser process exits for any reason, the CoreWebView2Environment will raise the BrowserProcessExited event. Use this event to synchronize operations involving the WebView2 Runtime resources and lifetime, such as User Data Folder management and updates. See Handle main browser process exited, below.

  • Main browser process crashes. When the main browser process crashes, it will produce both a ProcessFailed event and a BrowserProcessExited event, since the main browser process exited because of a failure.

Gathering process failure details

The ProcessFailed event provides detailed information about the process failure being reported. Your application can use and collect information from the event args for monitoring and diagnostics purposes, including process description (for utility processes only) and frames information (for renderer processes only).

Some process failures might raise the ProcessFailed event across different WebView2 controls in your application. You must decide how often to gather details and how to handle duplicates for these cases.

Additionally, most process crashes will generate dumps in the user data folder, under the directory returned by FailureReportFolderPath. You can use these dumps to understand crashes and provide additional information when contacting the WebView2 team.

Handle process crashes

When a crash occurs in the WebView2 Runtime, the ProcessFailed event will be raised for every WebView2 control associated to the crashing process. The failure might or might not be recoverable, and some failures are auto-recoverable.

You can use the following properties from the event args to identify the failure:

  • ProcessFailedKind. A combination of the process purpose (such as browser, renderer, or GPU) and failure (exit, unresponsiveness). Renderer processes are further divided in main frame renderer (RenderProcessExited, RenderProcessUnresponsive) and subframe renderer (FrameRenderProcessExited).

  • ProcessFailedReason. Indicates the category of the problem causing the failure. Some of these failure reasons are only applicable to specific failure kinds.

The main browser process has exited unexpectedly

All the WebView2 controls in your application using the same environment configuration will receive the ProcessFailed event with:

  • Failure kind: BrowserProcessExited.
  • Failure reason: any, except Unresponsive and LaunchFailed.

All associated WebView2 controls will be closed and your application must handle recovery from this failure. The WebView2 controls need to be recreated.

A single BrowserProcessExited event will be raised from the CoreWebview2Environment too, but the order of these events is not guaranteed. Your application must coordinate its event handlers for these two events when the browser process crashes. See Handle main browser process exited, below.

A process rendering content in the WebView2 control has exited unexpectedly

The content in impacted frames (main or subframe) is replaced with an error page. Every WebView2 control where content is impacted will receive the ProcessFailed event with:

  • Failure kind: RenderProcessExited or FrameRenderProcessExited.
  • Failure reason: any, except Unresponsive and ProfileDeleted.

Your application must handle recovery from this failure. If the main frame is impacted (RenderProcessExited), you can use the Reload API to reload content in your controls. Alternatively, you can Close and recreate the WebView2 controls.

If the main frame is not impacted (FrameRenderProcessExited), your application can communicate with the main frame to recover content in the impacted frames. The ProcessFailed event provides details for the impacted frames through the FrameInfosForFailedProcess property.

The GPU process has exited unexpectedly

The content in your WebView2 controls might flash as the process is automatically recreated. Every WebView2 control in the WebView2 Process Group will receive the ProcessFailed event with:

  • Failure kind: GpuProcessExited.
  • Failure reason: any, except Unresponsive and ProfileDeleted.

This is the most common WebView2 process failure and is auto-recoverable. Your application does not need to handle recovery for this event, but can collect information to understand any persistent issues, or if there is an underlying cause for repeated GPU process exits.

A utility process has exited unexpectedly

There might be some interruptions (for example, if the utility process was hosting the audio service) necessary processes are automatically recreated. Every WebView2 control in the WebView2 Process Group will receive the ProcessFailed event with:

  • Failure kind: UtilityProcessExited.
  • Failure reason: any, except Unresponsive and ProfileDeleted.

This process failure is not fatal and is auto-recoverable. Your application does not need to handle recovery for this event, but can collect information to understand any persistent issues, including the ProcessDescription provided in the event args.

Any other process has exited unexpectedly

Most processes in the WebView2 Process Group are associated to all WebView2 controls using it and will raise ProcessFailed to each control with:

  • Failure kind: PpapiBrokerProcessExited, PpapiPluginProcessExited, RenderProcessUnresponsive, SandboxHelperProcessExited, or UnknownProcessExited.
  • Failure reason: any, except Unresponsive and ProfileDeleted.

These process failures are not fatal and your application does not need to handle recovery for any of them, but can collect information to understand any persistent issues.

Handle unresponsive renderers

When the renderer process for the main frame in a WebView2 control becomes unresponsive to user input, the ProcessFailed event will be raised with:

  • Failure kind: RenderProcessUnresponsive.
  • Failure reason: Unresponsive.

The event will continue to be raised as long as the process remains unresponsive. Renderer process unresponsiveness can happen for the following reasons:

  • There is a long-running script being executed. For example, the web content in your WebView2 control might be performing a synchronous XHR, or have entered an infinite loop. Reloading the WebView2 control (by calling Reload) might make the control responsive again.

  • The system is busy.

This event will be raised repeatedly (for example, every 15 seconds), so you need to decide the threshold for your application to act upon it.

Handle main browser process exited

The BrowserProcessExited event indicates that the main browser process has exited and its resources (including its child processes) have been released. This can happen for the following reasons:

  • All WebView2 controls from the CoreWebView2Environment have been closed. Example app scenarios include:

    • Clearing the user data folder.
    • Updating the WebView2 Runtime.
    • Restarting with a different environment configuration.
    • Clearing the auth cache.

  • The main browser process failed. See The main browser process has exited unexpectedly, above.

This event is intended for operations involving the WebView2 Runtime resources. Your application can use the exit kind and the process ID from the event args to determine when and how to handle the event. For example, you might want coordinate with your ProcessFailed event handlers to prevent race conditions that could arise from attempting recovery while also trying to remove the user data folder.

Clearing the user data folder

Your application needs to wait until the WebView2 Runtime has released the User Data Folder before it can delete its contents. After closing all WebView2 controls, the BrowserProcessExited event indicates this has happened and your application can proceed with the operation.

See also:

Updating the WebView2 Runtime

In order to make use of the latest WebView2 Runtime after an update, your application needs to close all WebView2 controls and create a new CoreWebView2Environment. To ensure the new version is used, your application must wait for the BrowserProcessExited event; otherwise, the main browser process might stay alive when the new environment is created and switching to the new version would fail.

Restarting with a different environment configuration

Most of the configuration used for a CoreWebView2Environment is bound to the main browser process lifetime. In order to make changes to this configuration (for example, to language), your application needs to close existing WebView2 controls and wait for BrowserProcessExited before recreating the controls; otherwise, initializing the WebView2 controls from the new CoreWebView2Environment might fail with incompatible configuration.

Clearing the auth cache

The auth cache stores certificate selection and credentials from HTTPS Client Certificate Requests.

The auth cache is bound to the main browser process lifetime. Therefore, to clear the auth cache, your application must re-create its WebView2 controls from a new main browser process instance.

To ensure that a new main browser process instance is used when re-creating the WebView2 controls, your application must wait for the BrowserProcessExited event before proceeding; otherwise, the main browser process might stay alive when the controls are recreated, which would preserve the auth cache instead of clearing it as intended.

See also