Common Android Build and Runtime Errors (and How to Fix Them)

Net err_unknown_url_scheme appears in Android WebView when a custom URL scheme such as tel:, mailto:, or intent: is not intercepted before WebView tries to load it. The fix is to override shouldOverrideUrlLoading() inside your WebViewClient and route the custom scheme to an Android Intent instead of letting WebView handle it directly.

• Key Takeaway 1: ERR_UNKNOWN_URL_SCHEME is always a WebView interception problem, not a network error. Fix it in Java or Kotlin, not in your server config.
• Key Takeaway 2: AAPT2 resource linking failures almost always trace back to a duplicate resource ID, a missing namespace, or a broken dependency version in your build.gradle file.
• Key Takeaway 3: Manifest merger failures are caused by conflicting android:label, minSdkVersion, or permission declarations between your app and a third-party library.
• Key Takeaway 4: The emulator hardware acceleration error means HAXM is not installed or not enabled in your BIOS. It’s a one-time setup issue, not a code bug.
• Key Takeaway 5: Files in the assets/ folder load via file:///android_asset/, not via a standard file path. Getting the prefix wrong is the single most common cause of blank WebView screens.

Understanding net err_unknown_url_scheme and WebView URL Handling

When you embed a WebView in an Android app, it does not automatically know what to do with non-HTTP URLs. A link formatted as tel:+919876543210 or mailto:support@example.com does not map to a web page. WebView tries to load it anyway, fails, and throws net err_unknown_url_scheme.

The same thing happens with WhatsApp deep links (whatsapp://send?text=Hello) and custom app schemes used in payment gateways like Paytm or Razorpay. Indian developers building fintech or e-commerce apps hit this constantly because payment SDKs rely heavily on custom intent schemes to redirect back to the host app. According to Statista, India had approximately 4.5 million active Android developers as of 2023, making it one of the largest Android developer communities in the world — and net err_unknown_url_scheme is among the top five WebView errors reported on Stack Overflow India threads.

How to Fix net err_unknown_url_scheme in Java or Kotlin

The fix for net err_unknown_url_scheme lives inside your WebViewClient. Override shouldOverrideUrlLoading() and check the URL scheme before WebView attempts to render it. If the scheme is not http or https, create an Intent and call startActivity(). Wrap it in a try-catch to handle cases where no app on the device can respond to that scheme.

The pattern to follow: check the scheme, build the intent, catch ActivityNotFoundException, and show a user-friendly message if nothing handles it. That is the entire fix for net err_unknown_url_scheme. No third-party library needed.

Common schemes that trigger net err_unknown_url_scheme in Indian app contexts include tel: for click-to-call, upi: for UPI payment redirects, paytmmp:// for Paytm deep links, and intent: for generic Android intent URIs. Each one must be explicitly handled in shouldOverrideUrlLoading() or the error will recur.

The file:///android_asset/ Path and Why It Breaks

A related WebView problem is loading local HTML, CSS, or JavaScript from the app’s bundled assets. Files placed in the src/main/assets/ directory are accessible at runtime via the file:///android_asset/ prefix. The most common mistake is writing file:///android_assets/ (with an ‘s’) or using an absolute device path like /sdcard/ instead.

To load a file correctly, call webView.loadUrl("file:///android_asset/index.html"). You also need to enable webSettings.setAllowFileAccess(true) if you are loading files that reference other local resources. Without that flag, cross-origin local file loads silently fail on Android 10 and above.

The file sdcard open pattern, where developers try to read from the SD card path directly in WebView, is a separate issue. External storage access now requires runtime permissions under READ_EXTERNAL_STORAGE and, on Android 13+, the granular media permissions introduced in API level 33. If you are trying to index files on an SD card or display an index of file sdcard contents inside a WebView, you will need to copy them to the app’s internal cache first or serve them through a local HTTP server using something like NanoHTTPD.

AAPT2 Resource Linking Failures and Manifest Merger Errors

These two errors show up at build time, and they are responsible for a significant chunk of Android developer frustration. According to the Android Developers blog, AAPT2 became the default resource processing tool starting with Android Gradle Plugin 3.0.0, released in October 2017, affecting every project that upgraded from AGP 2.x. Any project still using patterns from pre-3.0 Gradle will hit compatibility issues.

Diagnosing “error failed linking file resources” from AAPT2

The full error message usually reads something like: AAPT2 error: check logs for details followed by error: failed linking references. The root cause is almost always one of three things: a resource file with an invalid character in its name, a duplicate resource defined in two modules, or a library dependency that ships resources targeting a higher compileSdkVersion than your project uses.

Start by running ./gradlew assembleDebug --stacktrace from your terminal. The full stack trace shows exactly which resource file and which line triggered the failure. Fix the named file first before touching anything else. Chasing the symptom in build.gradle without reading the trace wastes hours.

Fixing “manifest merger failed with multiple errors see logs”

This error means two or more modules declare the same attribute with incompatible values. The most frequent culprits are android:label in the application tag, minSdkVersion mismatches, and duplicate uses-permission declarations pulled in by ad SDKs or analytics libraries.

Open the Merged Manifest tab in Android Studio (go to app/src/main/AndroidManifest.xml, then click the tab at the bottom of the editor). It highlights every conflict in red with the source library shown beside it. For most conflicts, adding tools:replace="android:label" or tools:overrideLibrary="com.conflicting.library" in your own manifest resolves the issue cleanly.

If a third-party library targets a lower minSdkVersion than your app, use the overrideLibrary attribute, but only after you have confirmed the library actually runs on your minimum API level. Do not suppress the error blindly.

Emulator Hardware Acceleration and Storage Errors

The full error message is: emulator: ERROR: x86 emulation currently requires hardware acceleration. This appears when Android Studio’s emulator cannot access the CPU’s virtualisation extensions, which are needed to run x86 system images at native speed.

Enabling HAXM on Windows and Linux

On Windows, restart your machine, enter BIOS/UEFI settings, and enable Intel VT-x (for Intel CPUs) or AMD-V (for AMD CPUs). After that, open the Android Studio SDK Manager, go to SDK Tools, and install or repair Intel HAXM. On Linux, install KVM instead: run sudo apt-get install qemu-kvm libvirt-daemon-system and add your user to the kvm group.

According to Google’s Android Emulator documentation, HAXM-accelerated emulators run 5 to 10 times faster than non-accelerated ones for typical app testing workloads. Without acceleration, debugging on the emulator becomes practically unusable for UI-heavy apps.

If you are on a machine where BIOS access is restricted, which is common in college computer labs across India, use a physical Android device with USB debugging enabled instead. It is actually faster for most testing scenarios anyway.

SD Card and Storage Path Errors

Developers trying to fill sdcard content for testing, or reading an index of files from the SD card inside an emulator, often hit permission errors or wrong path assumptions. The emulator’s virtual SD card is mounted at /sdcard/, but accessing it from app code requires the correct runtime permission request and, on Android 11+, the MANAGE_EXTERNAL_STORAGE permission for broad access.

For emulator testing, you can push files to the virtual SD card using ADB: adb push localfile.txt /sdcard/. To index SD card contents programmatically, use Environment.getExternalStorageDirectory() on older APIs or the MediaStore API on Android 10 and above. Direct path access via /sdcard/ strings in code is deprecated and unreliable across device manufacturers.

If you are building apps that work with files heavily, Android development is one of the most practical technical skills a student can build before graduation, especially with India’s mobile-first economy growing rapidly.

Practical Fixes and Next Steps

Most Android build errors follow a pattern: the error message tells you exactly what is wrong, but it buries the useful line inside three layers of Gradle output. Training yourself to read stack traces instead of just the last error line is the single highest-leverage habit you can build as an Android developer.

Here is a quick checklist to work through when your build breaks:

1. Run ./gradlew assembleDebug --stacktrace and read the full output, not just the last 5 lines.
2. For AAPT2 errors, identify the exact resource file name mentioned in the trace.
3. For manifest errors, open the Merged Manifest tab in Android Studio before touching any code.
4. For net err_unknown_url_scheme, check every URL scheme your WebView content uses and handle each one in shouldOverrideUrlLoading().
5. For emulator acceleration errors, confirm virtualisation is enabled in BIOS before reinstalling HAXM.
6. For asset loading, triple-check the file:///android_asset/ prefix and verify setAllowFileAccess(true) is set.
7. Clean and rebuild (Build > Clean Project, then Build > Rebuild Project) after fixing any resource or manifest issue.

According to Stack Overflow’s 2023 Developer Survey, Android development remains one of the top five most-used technologies globally, with over 30% of professional developers working on mobile projects. Debugging build-time errors like net err_unknown_url_scheme is a daily reality for that community, not an edge case.

If you are still learning Android as part of a broader programming path, it helps to know which skills actually translate into jobs. Check out entry-level job opportunities for graduates that specifically value mobile development experience, and look at structured online courses that lead to high-salary roles in 2025 and beyond.

For students deciding where to focus next, choosing the right career path after graduation matters more than picking up every framework at once. Android development pairs well with cybersecurity skills, and platforms like free learning platforms let you build both without spending a lot upfront.

If you are weighing your options more broadly, the best career options for 2026 increasingly reward developers who understand both application-layer code and the security implications of what they build. That combination is exactly what 3.0 University’s certification programs in Cybersecurity, Ethical Hacking, AI, Blockchain, and Web3 are designed to build. Browse the full course catalogue to find a program that fits your current skill level and career target.

Frequently Asked Questions

What causes net err_unknown_url_scheme in a WebView?

Net err_unknown_url_scheme happens when a WebView tries to load a URL with a scheme it cannot handle natively, such as tel:, mailto:, intent:, upi:, or a custom app scheme like whatsapp://. WebView only handles http and https by default. You fix net err_unknown_url_scheme by overriding shouldOverrideUrlLoading() in your WebViewClient and routing the custom scheme to an Android Intent instead.

Why does net err_unknown_url_scheme appear in Android Chrome and not just WebView?

Net err_unknown_url_scheme can appear in Chrome for Android when a web page contains a link with a custom scheme and no installed app is registered to handle it. In a WebView context, the error is always a code-level interception problem. In Chrome, it usually means the target app is not installed on the device or the intent URI is malformed.

How do I fix net err_unknown_url_scheme for payment gateway redirects in India?

Payment gateways like Razorpay, Paytm, and PhonePe use custom schemes such as paytmmp:// and upi:// to redirect back to your app after a transaction. To fix net err_unknown_url_scheme for these flows, intercept every non-HTTP URL in shouldOverrideUrlLoading(), build an Intent from the URI, and call startActivity(). Catch ActivityNotFoundException to handle devices where the payment app is not installed.

How do you fix an AAPT2 resource linking error?

Run ./gradlew assembleDebug --stacktrace to get the full error output. AAPT2 resource linking failures almost always point to a specific file with an invalid name, a duplicate resource ID across modules, or a library dependency that requires a higher compileSdkVersion than your project declares. Fix the named resource first, then clean and rebuild the project.

How do you resolve a manifest merger failure?

Open the Merged Manifest tab in Android Studio to see exactly which attributes are conflicting and which library introduced them. Add tools:replace for simple attribute conflicts or tools:overrideLibrary for SDK version mismatches. Always verify the library actually supports your minSdkVersion before using overrideLibrary, since suppressing the warning without checking can cause runtime crashes on older devices.

Why does the emulator ask for hardware acceleration?

The Android emulator’s x86 system images require CPU virtualisation extensions (Intel VT-x or AMD-V) to run at usable speed. If those extensions are disabled in your BIOS or HAXM is not installed, the emulator refuses to start. Enable virtualisation in your BIOS settings, then install or repair Intel HAXM via the Android Studio SDK Manager. Linux users should install KVM instead of HAXM.

How do you load files from file:///android_asset?

Place your files in src/main/assets/ and load them with webView.loadUrl("file:///android_asset/yourfile.html"). The prefix is android_asset without an ‘s’. Also call webSettings.setAllowFileAccess(true) if your HTML references other local files. On Android 10 and above, cross-origin local file access is blocked by default, so test on a real device running the target API level.

Last updated: September 2026. Reviewed by the 3University editorial team.