{"record":{"id":"952d5a7b169153be","repo":"dotnet/maui","slug":"can-t-start-blazorwebview-without-native-web-view-952d5a","errorCode":null,"errorMessage":"Can't start BlazorWebView without native web view instance.","messagePattern":"Can't start BlazorWebView without native web view instance\\.","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"error","filePath":"src/BlazorWebView/src/Maui/iOS/BlazorWebViewHandler.iOS.cs","lineNumber":177,"sourceCode":"\t\t\t\t_webviewManager = null;\n\t\t\t}\n\t\t}\n\n\t\tprivate bool RequiredStartupPropertiesSet =>\n\t\t\t//_webview != null &&\n\t\t\tHostPage != null &&\n\t\t\tServices != null;\n\n\t\tprivate void StartWebViewCoreIfPossible()\n\t\t{\n\t\t\tif (!RequiredStartupPropertiesSet ||\n\t\t\t\t_webviewManager != null)\n\t\t\t{\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tif (PlatformView == null)\n\t\t\t{\n\t\t\t\tthrow new InvalidOperationException($\"Can't start {nameof(BlazorWebView)} without native web view instance.\");\n\t\t\t}\n\n\t\t\t// We assume the host page is always in the root of the content directory, because it's\n\t\t\t// unclear there's any other use case. We can add more options later if so.\n\t\t\tvar contentRootDir = Path.GetDirectoryName(HostPage!) ?? string.Empty;\n\t\t\tvar hostPageRelativePath = Path.GetRelativePath(contentRootDir, HostPage!);\n\n\t\t\tLogger.CreatingFileProvider(contentRootDir, hostPageRelativePath);\n\n\t\t\tvar fileProvider = VirtualView.CreateFileProvider(contentRootDir);\n\n\t\t\t_webviewManager = new IOSWebViewManager(\n\t\t\t\tthis,\n\t\t\t\tPlatformView,\n\t\t\t\tServices!,\n\t\t\t\tnew MauiDispatcher(Services!.GetRequiredService<IDispatcher>()),\n\t\t\t\tfileProvider,\n\t\t\t\tVirtualView.JSComponents,","sourceCodeStart":159,"sourceCodeEnd":195,"githubUrl":"https://github.com/dotnet/maui/blob/f377ff1c5ee04d334d8a925f50c83a6b7afddf03/src/BlazorWebView/src/Maui/iOS/BlazorWebViewHandler.iOS.cs#L159-L195","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// Guard before triggering webview start on iOS\nif (handler.PlatformView is null)\n{\n    return; // WKWebView not yet created\n}","typeGuard":"static bool HasIOSPlatformView(BlazorWebViewHandler handler)\n{\n    return handler?.PlatformView is not null;\n}","tryCatchPattern":"try\n{\n    // Code that may trigger webview initialization on iOS\n}\ncatch (InvalidOperationException ex) when (ex.Message.Contains(\"native web view instance\"))\n{\n    logger.LogWarning(\"iOS PlatformView (WKWebView) was null; deferring webview start.\");\n}","preventionTips":["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."],"tags":["blazor","blazorwebview","maui","ios","handler-lifecycle","platform-view","wkwebview"],"backgroundTag":null,"analyzedSha":"f377ff1c5ee04d334d8a925f50c83a6b7afddf03","analyzedAt":"2026-08-13T14:26:18.069Z","schemaVersion":2},"datasetVersion":"2026-08-13T19:17:28.613Z"}