Skip to content
WebView AllWebView All

Errors and Limits

This page lists important failures and platform limits that production code should handle.

APIFailure
loadRequest(Uri())Throws ArgumentError when the URI has no scheme.
loadFlutterAsset('')Throws or asserts because asset keys must not be empty.
loadFileThrows when the file does not exist on platforms that can validate it.
runJavaScriptReturningResultThrows when the result is null, undefined, or cannot be serialized.
callAsyncJavaScriptThrows ArgumentError for an empty body, invalid/reserved argument names, non-JSON arguments, non-finite numbers, or a non-positive timeout; rejected Promises and runtime errors produce JavaScriptExecutionException, and expiration produces TimeoutException.
addUserScriptThrows ArgumentError for empty source and UnsupportedError when the requested injection point is unavailable. Check isUserScriptInjectionSupported first.
addJavaScriptChannelThrows for duplicate names. Some platforms also require valid JavaScript identifiers.
setCookieThrows for invalid cookie names, domains, or paths.
PlatformAPIBehavior
AndroidloadRequest with POST and custom headersThrows because Android WebView postUrl cannot attach custom headers.
OHOSloadRequest with POST and custom headersThrows UnsupportedError because ArkWeb postUrl cannot attach custom headers.
WebloadFileThrows UnsupportedError; browsers cannot read arbitrary host files.
WebsetUserAgent(nonNull)Logs once and ignores the override; iframe network user agent cannot be changed by page JavaScript.
Webrecoverable SSL decisionsWebPlatformSslAuthError.proceed() and cancel() throw UnsupportedError.
Webcross-origin JavaScript and scroll APIsThrows UnsupportedError or silently cannot install hooks when browser policy blocks access.
Webcookie request for another originReturns an empty list and logs once; browser JavaScript cannot inspect that cookie jar.
Webdocument-start user scriptsCapability returns false because iframe APIs cannot guarantee execution before page scripts.
WebWebViewDataManager.clearAllWebsiteDataReturns every category as unsupported; a page cannot clear arbitrary iframe storage or HttpOnly cookies.
OHOSwebsite-data clearingSession storage, IndexedDB, Cache Storage, and service worker registrations are reported as unsupported.
Androiddocument-start user scripts on an older System WebViewCapability returns false; the app can continue without registering the script.
Windowswebsite-data clearingSession storage and service worker registrations are unsupported by the WebView2 profile API. Older runtimes without that API report every category as unsupported.
macOSscroll position, scroll callbacks, scrollbar visibility, and overscrollThe fork logs the missing public WKWebView API and safely no-ops; position reads return Offset.zero.
macOSversion-gated WebKit propertiesBackground color requires macOS 12 and inspection requires macOS 13.3. Earlier versions log and safely no-op.

For maximum portability:

  • Use GET for navigations that need custom headers on Android or OHOS.
  • Avoid POST custom headers if Android or OHOS are required.
  • For web, ensure the server sends the CORS headers required by your method and custom headers.
  • Use loadHtmlString as a fallback only when you control the response and do not need browser-native redirect, cookie, or service worker semantics.

Native platforms can surface recoverable SSL errors when their engine exposes them. The safe default is always:

onSslAuthError: (SslAuthError error) async {
await error.cancel();
}

Proceeding through a certificate error can expose users to interception. Keep proceed() for local development, test labs, or private certificate pinning experiments where you fully control the network.

On web, custom confirm and prompt callbacks for same-origin content must complete synchronously because browser JavaScript expects a synchronous return value:

await controller.setOnJavaScriptConfirmDialog((request) {
return SynchronousFuture<bool>(true);
});

If the callback completes later, the web implementation throws UnsupportedError.

The web platform cannot inspect or script cross-origin iframe content. This affects:

  • JavaScript execution
  • JavaScript channels
  • console hooks
  • dialog hooks
  • scroll APIs
  • title reads
  • resource error detail

Use same-origin content, loadHtmlString, or fetch-backed requests when those features are required. Plugin-managed isolated HTML uses a controlled message bridge. Direct cross-origin iframe URLs remain inaccessible, and isolated HTML keeps browser-native confirm and prompt dialogs.

clearAllWebsiteData is intentionally result-based so production logout code can distinguish a complete wipe from an engine limitation or native failure. Check result.isComplete; inspect unsupportedDataTypes and failures otherwise. The API does not fall back to clearing browsing history, passwords, autofill, or profile settings.

Web fetch-backed navigation keeps at most 100 typed history entries. Back and forward restore the stored response snapshot and never replay a mutating request; reload() is the explicit operation that refetches it. A navigation delegate denial leaves the current history index unchanged.

On Linux, navigation, HTTP authentication, TLS, permission, and JavaScript dialog decisions use a safe deny/cancel result if the application callback throws or returns an error. Native pending decisions also expire after 30 seconds. The failure is logged on one line so an application bug remains diagnosable without blocking WebKitGTK.

Windows initialization and rendering failures are shown in the widget and may be retried with Refresh. Rendering errors are latched so layout updates do not repeatedly restart a failed capture session. Install Webview2 is offered only for webview2_runtime_unavailable and opens the official WebView2 Runtime download page. Partial initialization state is released before a retry.

Windows initialization and rendering errors

Section titled “Windows initialization and rendering errors”
CodeStageMeaning
webview2_runtime_unavailablewebview2_runtimeNo compatible Runtime was found for the requested browser path.
environment_creation_failedwebview2_environmentWebView2 could not create the requested profile environment.
winrt_runtime_unavailable / winrt_initialization_failedwinrt_runtime / winrt_initializationThe Windows Runtime needed by the renderer could not be loaded or initialized.
graphics_capture_unavailable / graphics_capture_initialization_failedgraphics_captureGraphics capture is unavailable in the current OS, device, policy, or session.
dispatcher_queue_initialization_faileddispatcher_queueThe UI thread’s composition queue could not be reused or created.
d3d_device_creation_failedd3d_deviceNeither a hardware Direct3D device nor the WARP fallback could be created.
dxgi_device_initialization_faileddxgi_deviceThe Direct3D device does not expose the required DXGI interface.
d3d_interop_initialization_failedd3d_interopWindows Runtime Direct3D interop initialization failed.
composition_initialization_failedcompositionThe Windows Composition compositor could not be created.
webview_creation_failedwebview2_controllerController creation failed after environment setup.
graphics_capture_item_creation_failedgraphics_capture_itemThe composition visual could not be connected to Windows Graphics Capture.
graphics_capture_size_unavailablegraphics_capture_sizeThe capture item did not provide a valid surface size.
graphics_capture_frame_pool_creation_failedgraphics_capture_frame_poolThe UI-thread capture frame pool could not be created.
graphics_capture_frame_handler_registration_failedgraphics_capture_frame_handlerThe frame callback could not be registered.
graphics_capture_session_creation_failed / graphics_capture_start_failedgraphics_capture_session / graphics_capture_startThe capture session could not be created or started.
graphics_capture_resize_failedgraphics_capture_resizeThe capture frame pool could not be resized.
flutter_texture_registration_failedflutter_texture_registrationFlutter rejected the native texture registration.
invalid_surface_size / webview_surface_update_failedwebview_surface_size / webview_surfaceThe requested surface geometry was invalid or WebView2 rejected it.
webview_visibility_update_failedwebview_visibilityWebView2 could not apply the requested visible state.
website_data_clearing_failedwebview2_data_window / webview2_data_controller / webview2_data_webview / webview2_profile / webview2_website_dataThe isolated data window, temporary controller, WebView access, profile lookup, or clearing operation failed.

Windows native error details include stage, hexadecimal hresult, signed hresultValue, remoteSession, and webView2RuntimeVersion when detected. Equivalent concurrent ensureEnvironment calls share one native creation operation; conflicting configurations fail without replacing active or pending state.

On Windows and Linux, ensureEnvironment() with no options reuses the selected environment or initializes defaults. Explicit options must match the complete selected configuration. A mismatch returns environment_configuration_conflict; a second strict initializeEnvironment returns environment_already_initialized. Invalid or unavailable directories cause environment_creation_failed and may be retried after correcting the path. Website-data managers report these failures in their clearing result without clearing another environment.

PlatformLimit
WindowsWebView2 Runtime must be installed.
LinuxWebKitGTK 4.1 must be installed. The plugin installs its GtkOverlay automatically for the standard Flutter runner.
OHOSRequires OHOS Flutter SDK and API 22 or newer; ArkWeb behavior can vary by OS version and device.
AndroidWebView features depend on the installed Android System WebView/Chrome version.
iOS/macOSWebKit feature availability depends on OS version and app entitlements.