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 Android BlazorWebViewHandler's StartWebViewCoreIfPossible method checks that all required startup properties (HostPage, Services, etc.) are set, then attempts to create the webview manager. If PlatformView (the native Android WebView) is null at that point, there is no native view to attach Blazor to, so it throws. This typically indicates the handler was asked to start before the platform view was created by the Android view lifecycle.

Source

Thrown at src/BlazorWebView/src/Maui/Android/BlazorWebViewHandler.Android.cs:168

			_webViewClient?.Dispose();
			_webChromeClient?.Dispose();
		}

		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.");
			}

			// 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 AndroidWebKitWebViewManager(
				PlatformView,
				Services!,
				new MauiDispatcher(Services!.GetRequiredService<IDispatcher>()),
				fileProvider,
				VirtualView.JSComponents,
				contentRootDir,

View on GitHub (pinned to f377ff1c5e)

Solutions

Ensure the BlazorWebView is not conditionally shown/hidden in a way that triggers handler connect/disconnect cycles before initialization completes.
If using a custom handler, verify ConnectHandler properly creates and assigns the PlatformView before any property change notifications fire.
Upgrade to matching versions of the Microsoft.Maui.Controls and Microsoft.AspNetCore.Components.WebView.Maui packages.
Avoid calling StartWebViewCoreIfPossible or setting required properties before the handler has connected to its platform view.
File a bug if the error occurs with stock handlers and no custom lifecycle manipulation — it may indicate a framework-level race.

Defensive patterns

Strategy: validation

Validate before calling

// Guard before triggering webview start logic
if (handler.PlatformView is null)
{
    // Defer or log; do not call StartWebViewCoreIfPossible
    return;
}

Type guard

// Check if the handler has a valid platform view before interacting with it
static bool HasPlatformView(BlazorWebViewHandler handler)
{
    return handler?.PlatformView is not null;
}

Try / catch

try
{
    // Code that may trigger webview initialization
}
catch (InvalidOperationException ex) when (ex.Message.Contains("native web view instance"))
{
    // The platform view was not ready; defer initialization or retry after the view is attached
    logger.LogWarning("PlatformView was null during webview start; deferring.");
}

Prevention

Avoid conditionally mounting/unmounting BlazorWebView in layouts that recycle views.
If using a custom handler, ensure ConnectHandler creates PlatformView before property notifications.
Match MAUI and BlazorWebView package versions to avoid handler lifecycle mismatches.
Do not set required BlazorWebView properties (HostPage, Services) before the handler is connected.

When it happens

Trigger: StartWebViewCoreIfPossible is invoked (triggered by a property change or lifecycle event) but PlatformView — the native Android.Webkit.WebView created during ConnectHandler — is null. This can happen if the handler is disconnected, if the view was disposed, or if a framework lifecycle race causes the start to fire before ConnectHandler has run.

Common situations: Conditionally rendering a BlazorWebView inside a layout that mounts/unmounts rapidly; custom handler that overrides ConnectHandler but does not set PlatformView; platform-specific lifecycle on Android where OnElementChanged fires before the view is fully attached; disposing the page while a deferred start is pending; version mismatch between MAUI and the BlazorWebView package causing handler lifecycle differences.

Related errors

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