{"record":{"id":"a14132923c666572","repo":"dotnet/maui","slug":"can-t-start-blazorwebview-without-native-web-view","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/Android/BlazorWebViewHandler.Android.cs","lineNumber":168,"sourceCode":"\t\t\t_webViewClient?.Dispose();\n\t\t\t_webChromeClient?.Dispose();\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 AndroidWebKitWebViewManager(\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,\n\t\t\t\tcontentRootDir,","sourceCodeStart":150,"sourceCodeEnd":186,"githubUrl":"https://github.com/dotnet/maui/blob/f377ff1c5ee04d334d8a925f50c83a6b7afddf03/src/BlazorWebView/src/Maui/Android/BlazorWebViewHandler.Android.cs#L150-L186","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// Guard before triggering webview start logic\nif (handler.PlatformView is null)\n{\n    // Defer or log; do not call StartWebViewCoreIfPossible\n    return;\n}","typeGuard":"// Check if the handler has a valid platform view before interacting with it\nstatic bool HasPlatformView(BlazorWebViewHandler handler)\n{\n    return handler?.PlatformView is not null;\n}","tryCatchPattern":"try\n{\n    // Code that may trigger webview initialization\n}\ncatch (InvalidOperationException ex) when (ex.Message.Contains(\"native web view instance\"))\n{\n    // The platform view was not ready; defer initialization or retry after the view is attached\n    logger.LogWarning(\"PlatformView was null during webview start; deferring.\");\n}","preventionTips":["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."],"tags":["blazor","blazorwebview","maui","android","handler-lifecycle","platform-view"],"backgroundTag":null,"analyzedSha":"f377ff1c5ee04d334d8a925f50c83a6b7afddf03","analyzedAt":"2026-08-13T14:26:18.069Z","schemaVersion":2},"datasetVersion":"2026-08-13T19:17:28.613Z"}