Fix Ionic White Screen Issue on Android After Build

Gautam Amit February 18, 2026

In this article we are going to discuss how to fix white screen issue in android using ionic.

You spent hours building your Ionic app, everything looks great in the browser, and then you install it on an Android device and get a completely blank white screen. No error message, no crash dialog — just white. If this has happened to you, you are not alone. This is one of the most common issues developers face when building Ionic apps with Capacitor for Android.

The frustrating part is that Android does not tell you what went wrong. The app just silently fails to load. But once you understand the root causes, fixing it becomes straightforward.

This tutorial shows how to:

  • Use Chrome DevTools to find the real error on Android
  • Fix the Capacitor Android scheme setting
  • Fix Content Security Policy blocking your app
  • Handle HTTP cleartext traffic issues
  • Run a proper clean build
  • Fix incorrect build output path in Angular

Why the White Screen Happens on Android

Before jumping into fixes, it helps to understand why this happens in the first place.

When you run your Ionic app in the browser using ionic serve, it runs on a local development server over localhost. Everything works fine because the browser is flexible about how it loads resources.

But when you build the app and install it on Android, the app runs inside Android's WebView. WebView is much stricter than a regular browser. It has specific rules about how files are loaded, what URLs are allowed, and what kinds of network requests are permitted.

Here are the most common reasons the white screen appears:

  • Ionic is trying to load files using file:// paths that Android WebView blocks silently
  • Content Security Policy in index.html is too strict and blocks your own scripts or styles
  • Your app is making API calls to http:// endpoints that Android blocks by default
  • The www folder was not generated correctly before syncing to the Android project
  • The Angular build output path does not match what Capacitor expects

Any one of these can cause the entire app to fail with a white screen and no obvious error. The good news is that each one has a simple fix.

Step 1: Find the Real Error Using Chrome DevTools

The first thing you should always do before changing any code is find out what the actual error is. Android WebView supports remote debugging through Chrome DevTools, and this will show you exactly what is going wrong.

Enable USB Debugging on your Android device:

Go to Settings → About Phone and tap Build Number seven times to unlock Developer Options. Then go to Settings → Developer Options and enable USB Debugging.

Connect your device and open Chrome DevTools:

Connect your phone to your computer using a USB cable. Open Chrome on your desktop and navigate to:

chrome://inspect/#devices

Your Android device will appear in the list. Under your app's WebView, click Inspect. This opens a full Chrome DevTools window attached to your app running on the phone.

Go to the Console tab. You will see the actual JavaScript errors that are causing the white screen. This single step can save you hours of guessing.

Always do this first before trying any other fix.

Step 2: Fix the Android Scheme in Capacitor Config

This is the most common cause of the white screen in Ionic Capacitor apps and the first thing you should fix.

By default, older versions of Capacitor serve your app's files using file:// or capacitor:// URLs on Android. Modern Android WebView has issues with these schemes — things like cookies, localStorage, IndexedDB, and certain web APIs do not work properly or are blocked entirely when using file://. This causes the app to fail silently.

The fix is to set androidScheme to https in your Capacitor config.

Open your capacitor.config.ts file and update it like this:

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.yourapp.id',
  appName: 'YourApp',
  webDir: 'www',
  server: {
    androidScheme: 'https'
  }
};

export default config;

This tells Capacitor to serve your app's local files using https:// instead of file://. Android WebView handles https:// correctly and all browser APIs work as expected.

After making this change, always sync the config to the native project:

ionic build
npx cap sync android

Then rebuild from Android Studio and test on your device. This fix alone resolves the white screen for a large number of developers.

Step 3: Fix Content Security Policy in index.html

Content Security Policy, or CSP, is a security feature that controls what resources your web app is allowed to load. It is set using a <meta> tag in your src/index.html file.

If the CSP is too restrictive, it will block your app's own scripts, styles, or fonts from loading. When that happens, Angular cannot bootstrap and you get a white screen with no visible error in the app.

Open src/index.html and look for this tag:

<meta http-equiv="Content-Security-Policy" content="...">

Replace it with a CSP that works for Ionic on Android:

<meta http-equiv="Content-Security-Policy" 
  content="default-src 'self' data: gap: https://ssl.gstatic.com 'unsafe-eval' 'unsafe-inline'; 
           style-src 'self' 'unsafe-inline'; 
           media-src *; 
           img-src 'self' data: content:;">

If your app calls external APIs, you need to add those domains to the CSP as well. For example, if you call an API at https://api.yourbackend.com, add it like this:

<meta http-equiv="Content-Security-Policy" 
  content="default-src 'self' data: gap: https://ssl.gstatic.com https://api.yourbackend.com 'unsafe-eval' 'unsafe-inline'; 
           style-src 'self' 'unsafe-inline'; 
           media-src *; 
           img-src 'self' data: content:;">

Quick test: Temporarily remove the CSP meta tag entirely and rebuild. If the white screen disappears, you know CSP was the problem. Then add it back and adjust the policy until it works correctly.

Step 4: Allow HTTP Traffic for Development

Android, by default, blocks all network requests that go to http:// (non-HTTPS) endpoints. This is a security feature introduced in Android 9 and above.

If your app makes API calls to an http:// URL at startup — for example to load initial data or check authentication — Android will silently block those requests. If your app depends on that data to render the first screen, you will get a white screen.

To allow HTTP traffic during development, open your AndroidManifest.xml file located at:

android/app/src/main/AndroidManifest.xml

Add the usesCleartextTraffic attribute to the <application> tag:

<application
  android:usesCleartextTraffic="true"
  android:label="@string/app_name"
  android:icon="@mipmap/ic_launcher"
  ...>

Important: This setting should only be used during development and testing. Before you publish your app to the Google Play Store, remove this attribute and make sure all your API endpoints use HTTPS. Shipping an app with cleartext traffic enabled is a security risk and can affect your Play Store approval.

Step 5: Run a Proper Clean Build

Sometimes the Android project gets into a broken state after several builds, especially if you have been changing configuration files or updating packages. In this case, a clean rebuild is all you need.

First, do a fresh production build of your Ionic app:

ionic build --prod

This regenerates the www folder with your latest code. After the build finishes, check that www/index.html exists and has content. If the www folder is empty or missing, Capacitor has nothing to serve and will show a white screen.

Next, sync the updated files to Android:

npx cap sync android

Then open Android Studio. In the menu bar, go to:

Build → Clean Project

Wait for it to finish, then go to:

Build → Rebuild Project

After the rebuild completes, run the app on your device again. A clean rebuild clears any cached build artifacts that might have been causing the issue.

Step 6: Verify the Angular Build Output Path

If you are using Ionic with Angular, there is one more thing to check. Capacitor looks for your built files in the www folder. If Angular is outputting the build to a different folder, Capacitor will not find the files and the app will show a white screen.

Open your angular.json file and find the outputPath setting under your project's build configuration:

"architect": {
  "build": {
    "options": {
      "outputPath": "www"
    }
  }
}

Make sure it is set to "www". If it says something like "dist/app" or "dist/your-project-name", change it to "www" and run the build again.

Also check your capacitor.config.ts to confirm webDir matches:

const config: CapacitorConfig = {
  webDir: 'www'
};

Both values must point to the same folder.

Summary

You learned how to fix the Ionic white screen issue on Android after a build. You covered:

  • Using Chrome DevTools to inspect the Android WebView and find the real JavaScript error
  • Setting androidScheme: 'https' in capacitor.config.ts to fix file loading issues
  • Updating Content Security Policy in index.html to stop it from blocking your app
  • Adding usesCleartextTraffic="true" in AndroidManifest.xml for HTTP API calls during development
  • Running ionic build --prod followed by npx cap sync android and a clean rebuild in Android Studio
  • Confirming outputPath in angular.json is set to www

Follow these steps in order and you will be able to find and fix the white screen issue quickly. The Chrome DevTools step is especially important — it takes the guesswork out of debugging and points you directly to the problem.

I hope you like this article...

Happy coding! 🚀

Tags

Post a Comment

0 Comments