--- description: Troubleshoot common issues when building your Capacitor Android app, including Gradle version errors, plugin implementation issues, and blank screens. title: The Android Troubleshooting Guide for Capacitor - Capawesome image: https://capawesome.io/docs/assets/images/social/blog/troubleshooting-capacitor-android-issues.png --- [Skip to content ](#the-android-troubleshooting-guide-for-capacitor) [🖥️ Introducing the **Capacitor Electron Platform** — build desktop apps for macOS, Windows, and Linux. Free & open source. ](/blog/announcing-the-capacitor-electron-platform/) * [ SDKs ](/docs/sdks/) * [ Formbricks ](/docs/sdks/capacitor/formbricks/) * [ Geocoder ](/docs/sdks/capacitor/geocoder/) * [ Google Sign-In ](/docs/sdks/capacitor/google-sign-in/) * [ Grafana Faro ](/docs/sdks/capacitor/grafana-faro/) * [ Gyroscope ](/docs/sdks/capacitor/gyroscope/) * [ Haptics ](/docs/sdks/capacitor/haptics/) * [ Home Indicator ](/docs/sdks/capacitor/home-indicator/) * [ In-App Browser ](/docs/sdks/capacitor/in-app-browser/) * [ Install Referrer ](/docs/sdks/capacitor/install-referrer/) * [ Intercom ](/docs/sdks/capacitor/intercom/) * [ Intune ](/docs/sdks/capacitor/intune/) * [ Keep Awake ](/docs/sdks/capacitor/keep-awake/) * [ libSQL ](/docs/sdks/capacitor/libsql/) * [ Light Sensor ](/docs/sdks/capacitor/light-sensor/) * [ Live Update ](/docs/sdks/capacitor/live-update/) * [ Localization ](/docs/sdks/capacitor/localization/) * [ Mail Composer ](/docs/sdks/capacitor/mail-composer/) * [ Managed Configurations ](/docs/sdks/capacitor/managed-configurations/) * [ Maps Launcher ](/docs/sdks/capacitor/maps-launcher/) * [ Media Session ](/docs/sdks/capacitor/media-session/) * [ ML Kit ](/docs/sdks/capacitor/mlkit/) * [ Navigation Bar ](/docs/sdks/capacitor/navigation-bar/) * [ Network ](/docs/sdks/capacitor/network/) * [ NFC ](/docs/sdks/capacitor/nfc/) * [ Node.js ](/docs/sdks/capacitor/nodejs/) * [ OAuth ](/docs/sdks/capacitor/oauth/) * [ Passkeys ](/docs/sdks/capacitor/passkeys/) * [ Password Autofill ](/docs/sdks/capacitor/password-autofill/) * [ PDF Generator ](/docs/sdks/capacitor/pdf-generator/) * [ PDF Viewer ](/docs/sdks/capacitor/pdf-viewer/) * [ Pedometer ](/docs/sdks/capacitor/pedometer/) * [ Permissions ](/docs/sdks/capacitor/permissions/) * [ Phone Dialer ](/docs/sdks/capacitor/phone-dialer/) * [ Photo Editor ](/docs/sdks/capacitor/photo-editor/) * [ Photo Manipulator ](/docs/sdks/capacitor/photo-manipulator/) * [ PixLive ](/docs/sdks/capacitor/pixlive/) * [ PostHog ](/docs/sdks/capacitor/posthog/) * [ Printer ](/docs/sdks/capacitor/printer/) * [ Privacy Screen ](/docs/sdks/capacitor/privacy-screen/) * [ Proximity Sensor ](/docs/sdks/capacitor/proximity-sensor/) * [ Purchases ](/docs/sdks/capacitor/purchases/) * [ RealtimeKit ](/docs/sdks/capacitor/realtimekit/) * [ Root Detection ](/docs/sdks/capacitor/root-detection/) * [ Screen Brightness ](/docs/sdks/capacitor/screen-brightness/) * [ Screen Orientation ](/docs/sdks/capacitor/screen-orientation/) * [ Screen Reader ](/docs/sdks/capacitor/screen-reader/) * [ Screenshot ](/docs/sdks/capacitor/screenshot/) * [ Secure Preferences ](/docs/sdks/capacitor/secure-preferences/) * [ Settings Launcher ](/docs/sdks/capacitor/settings-launcher/) * [ Shake ](/docs/sdks/capacitor/shake/) * [ Silent Mode ](/docs/sdks/capacitor/silent-mode/) * [ SIM ](/docs/sdks/capacitor/sim/) * [ SMS Composer ](/docs/sdks/capacitor/sms-composer/) * [ Speech Recognition ](/docs/sdks/capacitor/speech-recognition/) * [ Speech Synthesis ](/docs/sdks/capacitor/speech-synthesis/) * [ Share Target ](/docs/sdks/capacitor/share-target/) * [ Square Mobile Payments ](/docs/sdks/capacitor/square-mobile-payments/) * [ SQLite ](/docs/sdks/capacitor/sqlite/) * [ Superwall ](/docs/sdks/capacitor/superwall/) * [ System WebView ](/docs/sdks/capacitor/system-webview/) * [ Tauri ](/docs/sdks/capacitor/tauri/) * [ Text Interaction ](/docs/sdks/capacitor/text-interaction/) * [ Text Zoom ](/docs/sdks/capacitor/text-zoom/) * [ Thermal State ](/docs/sdks/capacitor/thermal-state/) * [ Toast ](/docs/sdks/capacitor/toast/) * [ Torch ](/docs/sdks/capacitor/torch/) * [ Vault ](/docs/sdks/capacitor/vault/) * [ Volume ](/docs/sdks/capacitor/volume/) * [ Wallet ](/docs/sdks/capacitor/wallet/) * [ Wifi ](/docs/sdks/capacitor/wifi/) * [ YouTube Player ](/docs/sdks/capacitor/youtube-player/) * [ Zip ](/docs/sdks/capacitor/zip/) * [ Cordova ](/docs/sdks/cordova/) * [ Cloud ](/docs/cloud/) * [ Integrations ](/docs/cloud/live-updates/integrations/) * Concepts * Reference * [ Troubleshooting ](/docs/cloud/live-updates/troubleshooting/) * [ FAQ ](/docs/cloud/live-updates/faq/) * [ Native Builds ](/docs/cloud/native-builds/) * [ Set Up Environments ](/docs/cloud/native-builds/environments/) * [ Overwrite Native Configurations ](/docs/cloud/native-builds/native-configurations/) * [ Auto-Increment Build Numbers ](/docs/cloud/native-builds/auto-incrementing-build-numbers/) * [ Configure the Web Build Script ](/docs/cloud/native-builds/web-build-script/) * [ Build from a Monorepo ](/docs/cloud/native-builds/monorepo/) * [ Use pnpm, Yarn, or bun ](/docs/cloud/native-builds/package-managers/) * [ Install Private npm Packages ](/docs/cloud/native-builds/npm-private-registry/) * [ Override the Java Version ](/docs/cloud/native-builds/override-java-version/) * [ Custom iOS Provisioning Profiles ](/docs/cloud/native-builds/custom-ios-provisioning-profiles/) * [ Build without Git ](/docs/cloud/native-builds/build-without-git/) * [ Access Git Behind a Firewall ](/docs/cloud/native-builds/firewall-access/) * [ Integrations ](/docs/cloud/native-builds/integrations/) * Reference * [ Troubleshooting ](/docs/cloud/native-builds/troubleshooting/) * [ FAQ ](/docs/cloud/native-builds/faq/) * [ App Store Publishing ](/docs/cloud/app-store-publishing/) * [ Submit a Build ](/docs/cloud/app-store-publishing/submit-a-build/) * [ Submit Automatically After a Build ](/docs/cloud/app-store-publishing/submit-automatically/) * [ Troubleshooting ](/docs/cloud/app-store-publishing/troubleshooting/) * [ FAQ ](/docs/cloud/app-store-publishing/faq/) * [ Automations ](/docs/cloud/automations/) * [ Reference ](/docs/cloud/automations/reference/) * [ Troubleshooting ](/docs/cloud/automations/troubleshooting/) * [ FAQ ](/docs/cloud/automations/faq/) * [ Assist ](/docs/cloud/assist/) * [ CLI ](/docs/cloud/cli/) * APIs and SDKs * [ Webhooks ](/docs/cloud/webhooks/) * [ Integrations ](/docs/cloud/integrations/) * Account * [ Organization ](/docs/cloud/organizations/) * [ Two-Factor Enforcement ](/docs/cloud/organizations/two-factor-authentication/) * [ Audit Logs ](/docs/cloud/organizations/audit-logs/) * [ Billing ](/docs/cloud/organizations/billing/) * [ License Keys ](/docs/cloud/license-keys/) * [ AI ](/docs/ai/) * [ Insiders ](/docs/insiders/) * [ Billing & Plans ](/docs/insiders/billing-and-plans/) * [ FAQ ](/docs/insiders/faq/) * [ License ](https://capawesome.io/legal/eula/) * [ Support ](/docs/support/) * [ Contributing ](/docs/contributing/) * Contributing code * [ Code of Conduct ](/docs/contributing/code-of-conduct/) * [ Questions ](https://docs.github.com/en/discussions/collaborating-with-your-community-using-discussions/participating-in-a-discussion#creating-a-discussion) * [ Blog ](/blog/) * Categories * [ FAQ ](#faq) * [ Related Posts ](#related-posts) # The Android Troubleshooting Guide for Capacitor[¶](#the-android-troubleshooting-guide-for-capacitor "Permanent link") Capacitor is a great tool to build cross-platform apps with web technologies. However, sometimes you might run into issues when building your Android app. This post will help you to troubleshoot common issues. Help us to improve this guide If you are aware of any other common issues, please send us an email to [support@capawesome.io](mailto:support@capawesome.io) so that we can update the guide. ## Errors[¶](#errors "Permanent link") ### `Minimum supported Gradle version is 8.4. Current version is 8.2.1.`[¶](#minimum-supported-gradle-version-is-84-current-version-is-821 "Permanent link") This error occurs if you are using a version of the Android Gradle plugin that is incompatible with Capacitor. To fix the problem, you need to use the correct version of the Gradle plugin in your project. You can find the correct version in the [Capacitor documentation](https://capacitorjs.com/docs/). For Capacitor 6, for example, you must use version `8.2.1`. Update the Android Gradle plugin version in your root-level (project-level) Gradle file (usually `android/build.gradle`): android/build.gradle `[](#%5F%5Fcodelineno-0-1)buildscript { [](#%5F%5Fcodelineno-0-2) repositories { [](#%5F%5Fcodelineno-0-3) google() [](#%5F%5Fcodelineno-0-4) mavenCentral() [](#%5F%5Fcodelineno-0-5) } [](#%5F%5Fcodelineno-0-6) dependencies { [](#%5F%5Fcodelineno-0-7) classpath 'com.android.tools.build:gradle:8.2.1' [](#%5F%5Fcodelineno-0-8) } [](#%5F%5Fcodelineno-0-9)} ` ### Plugin is not implemented[¶](#plugin-is-not-implemented "Permanent link") If Capacitor cannot find a plugin or cannot inject its code into the WebView, the following error is thrown, for example: `[](#%5F%5Fcodelineno-1-1)"Badge" plugin is not implemented ` Follow the steps below to solve this issue: 1. Make sure that the plugin is installed and appears in the `package.json`. 2. Sync the native project by running `npx cap sync android`. 3. Sync the native project with Gradle files by using the `File` \-> `Sync Project with Gradle Files` button in Android Studio. 4. Make sure you are using Node.js version 22 or higher. ### Blank screen[¶](#blank-screen "Permanent link") A blank screen can have many causes. Here are some common reasons and solutions. #### With live reload[¶](#with-live-reload "Permanent link") If you see a blank screen when using live reload, check the following: 1. Make sure that your development server uses all network interfaces and not only `localhost`. For example, if you are using the Ionic CLI, you can use the `--external` option to bind to all network interfaces: `[](#%5F%5Fcodelineno-2-1)ionic cap run android -l --external ` 2. Make sure that your development server is accessible from the device. You can check this by opening the URL in the device's browser. If the URL is not accessible, the app will not be able to load the content. This may be due to the following reasons: * The device is not connected to the same network as the development server. * The development server is not accessible from the device due to firewall settings. 3. Make sure that the content is not blocked by a Content Security Policy (CSP) or other security mechanisms. You can check this by opening the browser's developer tools and looking for errors in the console. #### Without live reload[¶](#without-live-reload "Permanent link") If you see a blank screen without live reload, check the following: 1. Make sure you are using the latest WebView version. Capacitor requires Android 5.1 as well as a WebView version of 60 or higher. You can check the WebView version in the device's settings. 2. If you are using **Angular**, make sure that your `.browserslistrc` or `browserslist` file includes the browser versions you need to support. The Angular CLI uses this file to determine which code it can optimize. Check out [this topic](https://forum.ionicframework.com/t/ionic-6-default-project-white-screen-on-android-30-or-below-when-using-prod/228087) for more information. ## FAQ[¶](#faq "Permanent link") ### How do I clean and rebuild my Android project?[¶](#how-do-i-clean-and-rebuild-my-android-project "Permanent link") Many Gradle errors clear after a clean build. Run `./gradlew clean` in the `android` directory, or in Android Studio use **Build > Clean Project** followed by **Build > Rebuild Project**. If problems persist, invalidate caches with **File > Invalidate Caches / Restart**, then run `npx cap sync android` and sync the Gradle files again. ### How do I inspect the WebView and see console logs?[¶](#how-do-i-inspect-the-webview-and-see-console-logs "Permanent link") Open `chrome://inspect` in Google Chrome on your computer with the device connected and USB debugging enabled — it lists your app's WebView so you can attach DevTools to read console logs and inspect the DOM. For native-side logs, use `adb logcat` or the Logcat panel in Android Studio. ### Why don't my web code changes show up in the app?[¶](#why-dont-my-web-code-changes-show-up-in-the-app "Permanent link") Capacitor bundles your **built** web assets into the native app, so editing source files isn't enough. Rebuild the web app and copy it over with `npx cap sync android` (or `npx cap copy android`), then run the app again. During active development, use live reload so changes appear instantly. ### My device isn't detected by Android Studio or adb — what's wrong?[¶](#my-device-isnt-detected-by-android-studio-or-adb-whats-wrong "Permanent link") Make sure USB debugging is enabled and that you accepted the authorization prompt on the device. See [how to enable Developer Options on Android](/blog/how-to-enable-android-developer-mode/) for the full setup, and confirm you're using a data-capable USB cable with the **File transfer** USB mode. Running `adb devices` should list the device as `device`, not `unauthorized`. ### Which JDK version do I need?[¶](#which-jdk-version-do-i-need "Permanent link") Recent Capacitor and Android Gradle Plugin versions require JDK 17\. Point Android Studio at a JDK 17 (Gradle JDK under **Settings > Build, Execution, Deployment > Build Tools > Gradle**), and set `JAVA_HOME` to a JDK 17 for command-line builds. ### Where do I change the minSdk, targetSdk, or compileSdk?[¶](#where-do-i-change-the-minsdk-targetsdk-or-compilesdk "Permanent link") These are defined in `android/variables.gradle`. Edit the values there rather than in each module's `build.gradle`, so the whole project — including Capacitor plugins — stays consistent. ## Related Posts[¶](#related-posts "Permanent link") * [How to Fix Capacitor Plugin Build Errors with AGP 9](/blog/how-to-fix-capacitor-plugin-build-errors-with-agp-9/) * [How to patch a Capacitor plugin](/blog/how-to-patch-a-capacitor-plugin/) * [The iOS Troubleshooting Guide for Capacitor](/blog/troubleshooting-capacitor-ios-issues/) July 15, 2026 Back to top ```json { "@context": "https://schema.org", "@type": "BlogPosting", "headline": "The Android Troubleshooting Guide for Capacitor", "description": "Troubleshoot common issues when building your Capacitor Android app, including Gradle version errors, plugin implementation issues, and blank screens.", "image": "https://capawesome.io/assets/banners/cloud-build-and-deploy-capacitor-apps.png", "datePublished": "2024-04-12T00:00:00+00:00", "dateModified": "2026-07-14T00:00:00+00:00", "author": [ { "@type": "Person", "name": "Robin Genz", "url": "https://github.com/robingenz" } ], "publisher": { "@type": "Organization", "name": "Capawesome", "url": "https://capawesome.io", "logo": { "@type": "ImageObject", "url": "https://capawesome.io/assets/images/logo.svg" } }, "articleSection": "Capacitor", "keywords": ["Capacitor", "Guides"], "isPartOf": { "@type": "Blog", "@id": "https://capawesome.io/blog/#blog" }, "mainEntityOfPage": "https://capawesome.io/blog/troubleshooting-capacitor-android-issues/", "url": "https://capawesome.io/blog/troubleshooting-capacitor-android-issues/" } { "@context": "https://schema.org", "@type": "BreadcrumbList", "itemListElement": [ { "@type": "ListItem", "position": 1, "name": "Home", "item": "https://capawesome.io/" }, { "@type": "ListItem", "position": 2, "name": "Blog", "item": "https://capawesome.io/blog/" }, { "@type": "ListItem", "position": 3, "name": "The Android Troubleshooting Guide for Capacitor", "item": "https://capawesome.io/blog/troubleshooting-capacitor-android-issues/" } ] } {"@context": "https://schema.org", "@type": "FAQPage", "mainEntity": [{"@type": "Question", "name": "How do I clean and rebuild my Android project?", "acceptedAnswer": {"@type": "Answer", "text": "Many Gradle errors clear after a clean build. Run./gradlew clean in the android directory, or in Android Studio use Build > Clean Project followed by Build > Rebuild Project. If problems persist, invalidate caches with File > Invalidate Caches / Restart, then run npx cap sync android and sync the Gradle files again."}}, {"@type": "Question", "name": "How do I inspect the WebView and see console logs?", "acceptedAnswer": {"@type": "Answer", "text": "Open chrome://inspect in Google Chrome on your computer with the device connected and USB debugging enabled — it lists your app's WebView so you can attach DevTools to read console logs and inspect the DOM. For native-side logs, use adb logcat or the Logcat panel in Android Studio."}}, {"@type": "Question", "name": "Why don't my web code changes show up in the app?", "acceptedAnswer": {"@type": "Answer", "text": "Capacitor bundles your built web assets into the native app, so editing source files isn't enough. Rebuild the web app and copy it over with npx cap sync android (or npx cap copy android), then run the app again. During active development, use live reload so changes appear instantly."}}, {"@type": "Question", "name": "My device isn't detected by Android Studio or adb — what's wrong?", "acceptedAnswer": {"@type": "Answer", "text": "Make sure USB debugging is enabled and that you accepted the authorization prompt on the device. See how to enable Developer Options on Android for the full setup, and confirm you're using a data-capable USB cable with the File transfer USB mode. Running adb devices should list the device as device, not unauthorized."}}, {"@type": "Question", "name": "Which JDK version do I need?", "acceptedAnswer": {"@type": "Answer", "text": "Recent Capacitor and Android Gradle Plugin versions require JDK 17. Point Android Studio at a JDK 17 (Gradle JDK under Settings > Build, Execution, Deployment > Build Tools > Gradle), and set JAVA_HOME to a JDK 17 for command-line builds."}}, {"@type": "Question", "name": "Where do I change the minSdk, targetSdk, or compileSdk?", "acceptedAnswer": {"@type": "Answer", "text": "These are defined in android/variables.gradle. Edit the values there rather than in each module's build.gradle, so the whole project — including Capacitor plugins — stays consistent."}}], "url": "https://capawesome.io/blog/troubleshooting-capacitor-android-issues/"} ```