The Android Troubleshooting Guide for Capacitor¶

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 [email protected] so that we can update the guide.

Errors¶

`Minimum supported Gradle version is 8.4. Current version is 8.2.1.`¶

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.

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

buildscript {
    repositories {
        google()
        mavenCentral()
    }
    dependencies {
        classpath 'com.android.tools.build:gradle:8.2.1'
    }
}

Blank screen¶

A blank screen can have many causes. Here are some common reasons and solutions.

With live reload¶

If you see a blank screen when using live reload, check the following:

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:
```
ionic cap run android -l --external
```
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.
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¶

If you see a blank screen without live reload, check the following:

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 for more information.