A WhatsApp link in Flutter WebView fails with unknown URL scheme
net::ERR_UNKNOWN_URL_SCHEMEShort 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.
Fix it fast
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; },2Match what you see, then jump to its fix
- 1
The log prints whatsapp://... right before the error pageThe scheme is not http or https, so nothing in the WebView can open itFix - 2
Your page or HTML uses whatsapp://send?phone=...The link is a whatsapp:// scheme instead of a wa.me web linkFix - 3
You guard the launch with canLaunchUrl and nothing happenscanLaunchUrl says false on Android 11 or later and iOSFix
- 1
What does the error look like?
net::ERR_UNKNOWN_URL_SCHEMEThe 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 runConfirmed by pub.dev
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%20there3Verify
Open the link in a normal browser first; it should offer WhatsApp.
# open the wa.me link in a phone browserConfirmed by faq.whatsapp.com
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.plist2Fix
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 runConfirmed by pub.dev
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:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- Dispatch ProA real-time logistics platform: Flutter apps, Spring Boot services and a Kafka event pipeline on AWS.
- Qist BazaarA buy-now-pay-later marketplace built from a blank repo, now past 100K downloads on Google Play.
Related fixes
Mobile apps
WebView shows an error when a link opens another app, such as a Facebook link
ERROR_UNSUPPORTED_SCHEME
A WebView only loads web schemes.
2 causes, each with a fixMobile 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 fixMobile apps
Gradle cannot find com.google.firebase:firebase-analytics-ktx
Required by: project :app
Firebase moved the Kotlin extensions into the main modules and stopped releasing the -ktx modules in July 2025.
2 causes, each with a fixMobile apps
Gradle cannot create LibraryVariantBuilderImpl in a Flutter Android build
Could not create an instance of type com.android.build.api.variant.impl.LibraryVariantBuilderImpl
This error appears when the Android Gradle plugin (AGP) cannot run in the Gradle or IDE you use.
3 causes, each with a fixMobile apps
Flutter release build cannot open the keystore: HmacPBESHA256 not available
Algorithm HmacPBESHA256 not available
The keystore is a PKCS12 file protected by a newer algorithm than the Java that is reading it understands.
3 causes, each with a fixMobile apps
Android install error: the package conflicts with an existing package of the same name
The package conflicts with an existing package by the same name
Android allows only one app per application ID, and an update must be signed with the same certificate as the installed version.
3 causes, each with a fix