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 iOS BlazorWebViewHandler's StartWebViewCoreIfPossible checks PlatformView (the native WKWebView) is non-null before constructing the IOSWebViewManager. On iOS, the WKWebView must be created by ConnectHandler before Blazor can attach. A null PlatformView means the handler started before view creation or after teardown.

Source

Thrown at src/BlazorWebView/src/Maui/iOS/BlazorWebViewHandler.iOS.cs:177

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

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

View on GitHub (pinned to f377ff1c5e)

Solutions

Ensure WKWebView is created in ConnectHandler before property change notifications can fire StartWebViewCoreIfPossible.
Avoid placing BlazorWebView inside recycled views (CarouselView, CollectionView, TabbedPage) unless the handler lifecycle is managed explicitly.
If using a custom handler, preserve the platform view lifecycle exactly as the default handler does.
Update to compatible versions of Microsoft.Maui.Controls and Microsoft.AspNetCore.Components.WebView.Maui.
Test on a physical device — simulators may exhibit different WKWebView lifecycle timing.

Defensive patterns

Strategy: validation

Validate before calling

// Guard before triggering webview start on iOS
if (handler.PlatformView is null)
{
    return; // WKWebView not yet created
}

Type guard

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

Try / catch

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

Prevention

Avoid placing BlazorWebView inside recycled views (CarouselView, CollectionView) on iOS.
Create WKWebView in ConnectHandler before property notifications fire.
Test on physical devices, not just simulators, to catch lifecycle timing issues.
Keep Microsoft.Maui.Controls and BlazorWebView.iOS packages version-aligned.

When it happens

Trigger: RequiredStartupPropertiesSet is true but PlatformView (WKWebView) is null when StartWebViewCoreIfPossible fires. This can occur due to UIKit lifecycle ordering, especially on view controllers that load/unload rapidly, or when the handler is reused after disconnection.

Common situations: iOS view controller lifecycle where ViewDidLoad/ViewWillDisappear ordering causes handler connect/disconnect before the deferred start; using BlazorWebView inside a TabbedPage or CarouselView where cells are recycled; custom handler overriding ConnectHandler on iOS without assigning PlatformView; memory pressure causing iOS to purge the WKWebView; MAUI/iOS package version mismatch.

Related errors

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