Skip to content
WebView AllWebView All
Documentation for version 1.2.x; select latest for up-to-date APIs.

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.
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)Throws UnsupportedError; iframe user agent cannot be overridden 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.
macOSselected UIKit-backed WebKit propertiesMay throw UnimplementedError in the official WK package.

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, confirm and prompt callbacks 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.

PlatformLimit
WindowsWebView2 Runtime must be installed.
LinuxWebKitGTK 4.1 must be installed and the runner must use GtkOverlay.
OHOSRequires OHOS Flutter SDK and ArkWeb behavior can vary by API level.
AndroidWebView features depend on the installed Android System WebView/Chrome version.
iOS/macOSWebKit feature availability depends on OS version and app entitlements.