dotnet/maui · error · InvalidOperationException

Can't start BlazorWebView without native web view instance.

Error message

Can't start BlazorWebView without native web view instance.

What it means

The Windows BlazorWebViewHandler's StartWebViewCoreIfPossible checks that PlatformView (the native Windows WebView2 wrapper) is non-null. On Windows, the underlying CoreWebView2 is instantiated asynchronously, but the PlatformView container (the WebView2 control) must exist before the manager can be created. If it is null, the handler was started before the platform view was attached or after it was disconnected.

Source

Thrown at src/BlazorWebView/src/Maui/Windows/BlazorWebViewHandler.Windows.cs:71

				_webviewManager = null;
			}
		}

		private bool RequiredStartupPropertiesSet =>
			//_webview != null &&
			HostPage != null &&
			Services != null;

		private void StartWebViewCoreIfPossible()
		{
			if (!RequiredStartupPropertiesSet ||
				_webviewManager != null)
			{
				return;
			}
			if (PlatformView == null)
			{
				throw new InvalidOperationException($"Can't start {nameof(BlazorWebView)} without native web view instance.");
			}

			var logger = Services!.GetService<ILogger<BlazorWebViewHandler>>() ?? NullLogger<BlazorWebViewHandler>.Instance;

			// We assume the host page is always in the root of the content directory, because it's
			// unclear there's any other use case. We can add more options later if so.
			var contentRootDir = Path.GetDirectoryName(HostPage!) ?? string.Empty;
			var hostPageRelativePath = Path.GetRelativePath(contentRootDir, HostPage!);

			logger.CreatingFileProvider(contentRootDir, hostPageRelativePath);
			var fileProvider = VirtualView.CreateFileProvider(contentRootDir);

			_webviewManager = new WinUIWebViewManager(
				PlatformView,
				Services!,
				new MauiDispatcher(Services!.GetRequiredService<IDispatcher>()),
				fileProvider,
				VirtualView.JSComponents,

View on GitHub (pinned to f377ff1c5e)

Solutions

  1. Avoid navigating away from the page containing BlazorWebView before its initialization completes.
  2. If using a custom handler, ensure PlatformView is created in ConnectHandler and not nulled until DisconnectHandler completes.
  3. Verify package versions: Microsoft.AspNetCore.Components.WebView.Maui, Microsoft.UI.Xaml, and Microsoft.WindowsAppSDK must be compatible.
  4. Use the default BlazorWebViewHandler unless you have a specific reason to customize, and ensure any customization preserves the view lifecycle.
  5. Ensure the WebView2 runtime is installed on the target Windows machine.
Defensive patterns

Strategy: validation

Validate before calling

// Guard before triggering webview start on Windows
if (handler.PlatformView is null)
{
    return; // WebView2 host control not yet created
}

Type guard

static bool HasWindowsPlatformView(BlazorWebViewHandler handler)
{
    return handler?.PlatformView is not null;
}

Try / catch

try
{
    // Code that may trigger webview initialization on Windows
}
catch (InvalidOperationException ex) when (ex.Message.Contains("native web view instance"))
{
    logger.LogWarning("Windows PlatformView was null; deferring webview start.");
}

Prevention

When it happens

Trigger: RequiredStartupPropertiesSet is true (HostPage, Services set) but PlatformView — the WinUI/Microsoft.UI.Xaml.Controls.WebView2 host — is null when StartWebViewCoreIfPossible runs. This can happen during window teardown, when the handler is disconnected, or due to a WinUI lifecycle ordering issue.

Common situations: WinUI 3 window disposal triggering a property change after the platform view is torn down; navigation away from a page containing BlazorWebView before initialization completes; custom handler overriding DisconnectHandler or ConnectHandler without preserving PlatformView lifecycle; package version mismatch between Microsoft.UI.Xaml and the BlazorWebView MAUI package; rapid page navigation causing handler reuse before previous cleanup.

Related errors

AI-assisted analysis of dotnet/maui@f377ff1c5e (2026-08-13). Data as JSON: /api/errors/f5254c1e9fc93bd8. Report an issue: GitHub.