Diagnosing White Screen of Death in Ionic Capacitor Apps

Recognizable condition

The app launches on a physical device or emulator, shows a splash screen, then displays a completely white viewport with no UI elements. No error toast appears, and the JavaScript console is silent when viewed from a desktop browser.

Common causes at a glance

Ordered diagnostic checks

1. Attach a remote debugger

   Run the app on a connected device with live reload disabled so the production bundle loads:

   ionic capacitor run android --prod --no-livereload
   # or for iOS
   ionic capacitor run ios --prod --no-livereload

   Then open chrome://inspect (Android) or Safari → Develop → [Device] → [App] (iOS). Look at the Console tab for any red error lines. Expected check: a stack trace pointing to a specific file and line number. Risk: enabling --prod disables source maps; keep a debug build handy for mapping.

2. Validate base href

   Open src/index.html (or the generated www/index.html) and confirm the <base href="/"> matches the deployment path. If the app is hosted under /myapp/, the tag must be <base href="/myapp/">. Rebuild after any change:

   ionic build --prod
   ionic capacitor copy android
   ionic capacitor copy ios

   Expected check: network tab shows 200 for all .js and .css requests. Risk: an incorrect base href produces 404s that are silent on the console because the bootstrap script never loads.

3. Inspect Content Security Policy

   Locate the CSP meta tag in index.html. A typical strict policy looks like:

   <meta http-equiv="Content-Security-Policy" content="default-src 'self' https: data:; script-src 'self' 'unsafe-inline' 'unsafe-eval'; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:;>

   Remove 'unsafe-inline' and 'unsafe-eval' only if you have no inline scripts or eval() usage. Test by temporarily relaxing the policy to default-src * 'unsafe-inline' 'unsafe-eval'; and see if the white screen disappears. Expected check: console shows CSP violation reports pointing to blocked resources. Risk: overly permissive CSP weakens security; restore a strict policy after identifying the blocked asset.

4. Check native plugin compatibility

   Run the native IDE and watch the device log while the app starts:

   # Android
   adb logcat -s "Capacitor","WebView","Chromium"
   # iOS (in Xcode console filter by the app name)

   Look for lines such as Plugin "Camera" not found or TypeError: Cannot read property 'getPhoto' of undefined. Verify that the plugin’s JavaScript package version matches the native pod / Gradle dependency. Example: @capacitor/camera@5.0.0 requires CapacitorCamera pod version 5.x. Update both sides:

   npm install @capacitor/camera@latest
   ionic capacitor update android
   ionic capacitor update ios

   Expected check: no plugin‑related crashes in native logs. Risk: updating plugins may introduce breaking API changes; run the test suite after each upgrade.

5. Audit root component initialization

   Open src/app/app.component.ts (or the framework‑specific root). Ensure the constructor does not perform async work, heavy calculations, or subscribe to observables that never complete. Move any initialization to ngOnInit or a dedicated initializeApp() method called after platform.ready().

   constructor(private platform: Platform) {
     this.platform.ready().then(() => this.initializeApp());
   }
   
   private async initializeApp() {
     // safe to call plugins here
     await SplashScreen.hide();
   }

   Expected check: the console shows Platform ready and no “Maximum call stack size exceeded” or long‑running script warnings. Risk: moving code out of the constructor can change lifecycle timing; verify that any guards or route resolvers still receive required data.

Fixes tied to findings

• JS bootstrap error – fix the reported syntax/type error, rebuild, and redeploy.
• Base href mismatch – correct the tag, rebuild, and run capacitor copy for each platform.
• CSP violation – add the blocked domain or hash to the policy; avoid eval() and inline scripts in production.
• Plugin mismatch – align JS and native versions, then run capacitor sync.
• Root component blockage – refactor heavy work out of the constructor; use platform.ready() guard.

Escalation criteria

Escalate to a platform‑specific debugging session when:

• No JavaScript errors appear in the remote console, yet the native logs show a WebView crash (e.g., SIGSEGV on Android or EXC_BAD_ACCESS on iOS).
• All CSP, base href, and plugin checks pass, but the screen remains white on multiple devices.
• The issue reproduces only on a specific OS version (e.g., Android 14 WebView 115) indicating a WebView bug.

In those cases, capture a full native crash dump (Android: adb bugreport; iOS: Xcode → Devices → View Device Logs) and file an issue with the Capacitor or WebView maintainers.

Quick verification checklist

1. Remote console shows zero errors after fix.
2. Network tab loads all bundles with 200 OK.
3. CSP reports no violations in the console.
4. Native logs show clean WebView start‑up.
5. App renders the first page within 2 seconds on a cold start.