Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Flutter and app store releases

A WhatsApp link in Flutter WebView fails with unknown URL scheme

Errornet::ERR_UNKNOWN_URL_SCHEME

Short answer

A WebView only loads web pages. A whatsapp:// link has no handler inside it, so Android shows net::ERR_UNKNOWN_URL_SCHEME. Intercept the navigation in NavigationDelegate, stop it, and hand the link to the phone with url_launcher. Use the https wa.me link format, which WhatsApp documents.

  • Applies to webview_flutter 4, url_launcher 6, Flutter 3.35
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Print every URL the WebView tries to open, to see the exact scheme being blocked.

    onNavigationRequest: (NavigationRequest r) {
      debugPrint(r.url);
      return NavigationDecision.navigate;
    },
  2. 2Match what you see, then jump to its fix

    1. 1The log prints whatsapp://... right before the error pageThe scheme is not http or https, so nothing in the WebView can open itFix
    2. 2Your page or HTML uses whatsapp://send?phone=...The link is a whatsapp:// scheme instead of a wa.me web linkFix
    3. 3You guard the launch with canLaunchUrl and nothing happenscanLaunchUrl says false on Android 11 or later and iOSFix

What does the error look like?

  • net::ERR_UNKNOWN_URL_SCHEME
  • The WebView shows an error page when a WhatsApp button is tapped

Cause 1 of 3

The scheme is not http or https, so nothing in the WebView can open it

1Check

onNavigationRequest sees each navigation and can return NavigationDecision.prevent.

grep -rn "NavigationDelegate" lib/

2Fix

Prevent the in-app load for that scheme and launch it with url_launcher, which sends the URL to the host platform.

onNavigationRequest: (request) async {
  final uri = Uri.parse(request.url);
  if (uri.scheme != 'http' && uri.scheme != 'https') {
    await launchUrl(uri, mode: LaunchMode.externalApplication);
    return NavigationDecision.prevent;
  }
  return NavigationDecision.navigate;
},

3Verify

Tap the link; WhatsApp opens, and the WebView stays on the page.

flutter run

Confirmed by pub.dev

Did this fix it?

Cause 2 of 3

The link is a whatsapp:// scheme instead of a wa.me web link

1Check

WhatsApp documents https://wa.me/<number> for Click to Chat, with the number in full international format without a plus, zeros, brackets or dashes.

grep -rn "whatsapp://" assets/ lib/

2Fix

Use the wa.me form, and URL-encode any pre-filled text.

https://wa.me/1XXXXXXXXXX?text=Hello%20there

3Verify

Open the link in a normal browser first; it should offer WhatsApp.

# open the wa.me link in a phone browser

Confirmed by faq.whatsapp.com

Did this fix it?

Cause 3 of 3

canLaunchUrl says false on Android 11 or later and iOS

1Check

url_launcher requires every scheme passed to canLaunchUrl as a <queries> entry on Android (API 30+) and in LSApplicationQueriesSchemes on iOS, and canLaunchUrl can return false even when launchUrl would work.

grep -n "queries\|LSApplicationQueriesSchemes" android/app/src/main/AndroidManifest.xml ios/Runner/Info.plist

2Fix

Call launchUrl directly and handle failure, or add the scheme to both lists.

<queries>
  <intent>
    <action android:name="android.intent.action.VIEW" />
    <data android:scheme="whatsapp" />
  </intent>
</queries>

3Verify

Rebuild fully and tap the link again.

flutter clean && flutter run

Confirmed by pub.dev

Did this fix it?

How do I stop it coming back?

  • Handle every non-http scheme (tel, mailto, whatsapp) in one NavigationDelegate branch.
  • Prefer https wa.me links in web content you control.
  • Test on a phone that has WhatsApp installed and one that does not.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Mobile apps

Google Play says the app does not support 16 KB memory pages

check_elf_alignment.sh reports UNALIGNED for a library under lib/arm64-v8a

Google Play requires apps that target Android 15 or higher and ship native .so libraries to run on devices with 16 KB memory pages; from 1 February 2027 it will block updates that do not.

5 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.