{"record":{"id":"f5254c1e9fc93bd8","repo":"dotnet/maui","slug":"can-t-start-blazorwebview-without-native-web-view-f5254c","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/Windows/BlazorWebViewHandler.Windows.cs","lineNumber":71,"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\tvar logger = Services!.GetService<ILogger<BlazorWebViewHandler>>() ?? NullLogger<BlazorWebViewHandler>.Instance;\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\t\t\tvar fileProvider = VirtualView.CreateFileProvider(contentRootDir);\n\n\t\t\t_webviewManager = new WinUIWebViewManager(\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":53,"sourceCodeEnd":89,"githubUrl":"https://github.com/dotnet/maui/blob/f377ff1c5ee04d334d8a925f50c83a6b7afddf03/src/BlazorWebView/src/Maui/Windows/BlazorWebViewHandler.Windows.cs#L53-L89","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Avoid navigating away from the page containing BlazorWebView before its initialization completes.","If using a custom handler, ensure PlatformView is created in ConnectHandler and not nulled until DisconnectHandler completes.","Verify package versions: Microsoft.AspNetCore.Components.WebView.Maui, Microsoft.UI.Xaml, and Microsoft.WindowsAppSDK must be compatible.","Use the default BlazorWebViewHandler unless you have a specific reason to customize, and ensure any customization preserves the view lifecycle.","Ensure the WebView2 runtime is installed on the target Windows machine."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// Guard before triggering webview start on Windows\nif (handler.PlatformView is null)\n{\n    return; // WebView2 host control not yet created\n}","typeGuard":"static bool HasWindowsPlatformView(BlazorWebViewHandler handler)\n{\n    return handler?.PlatformView is not null;\n}","tryCatchPattern":"try\n{\n    // Code that may trigger webview initialization on Windows\n}\ncatch (InvalidOperationException ex) when (ex.Message.Contains(\"native web view instance\"))\n{\n    logger.LogWarning(\"Windows PlatformView was null; deferring webview start.\");\n}","preventionTips":["Ensure the WebView2 runtime is installed on the target machine.","Avoid navigating away from pages with BlazorWebView before initialization completes.","If using a custom handler, preserve PlatformView lifecycle in Connect/DisconnectHandler.","Keep Microsoft.UI.Xaml, Microsoft.WindowsAppSDK, and BlazorWebView packages version-aligned."],"tags":["blazor","blazorwebview","maui","windows","handler-lifecycle","platform-view","webview2"],"backgroundTag":null,"analyzedSha":"f377ff1c5ee04d334d8a925f50c83a6b7afddf03","analyzedAt":"2026-08-13T14:26:18.069Z","schemaVersion":2},"datasetVersion":"2026-08-13T19:17:28.613Z"}