Phase 7

Troubleshooting

The errors you will actually hit

As needed

Symptom-first fixes for the failures that come up again and again. Search this page before you search the web.

The app opens to a white screen

Connect the device and open chrome://inspect in desktop Chrome (Android) or Safari → Develop (iOS). Read the console.
Wrong `webDir` — it must match your build output folder exactly.
You forgot to rebuild — run npm run build before npx cap sync.
A leftover `server.url` in capacitor.config.ts pointing at a dev machine.
Absolute asset paths — the app is served from capacitor://localhost, so a path assuming a domain root can 404.
A crash during render — an unguarded browser API on the first screen.

Changes do not appear in the app

bash

npm run build && npx cap sync && npx cap open android

If it still shows the old UI: uninstall the app from the device (stale web-view cache), then Build → Clean Project in Android Studio and reinstall.

Gradle and JDK errors

Message	Cause and fix
`Unsupported class file major version`	Wrong JDK. Android Studio → Settings → Build Tools → Gradle → set Gradle JDK to 17.
`SDK location not found`	Create `android/local.properties` with `sdk.dir=/path/to/Android/sdk`.
`Could not resolve com.android.tools.build:gradle`	No network or a proxy; check `gradle-wrapper.properties` distribution URL.
`Execution failed for task ':app:processReleaseResources'`	Usually a malformed icon or an XML asset; regenerate assets and clean.
`Daemon disappeared` / OOM	Add `org.gradle.jvmargs=-Xmx4096m` to `android/gradle.properties`.

bash

cd android && ./gradlew clean && ./gradlew --stop && ./gradlew bundleRelease

Signing and upload rejections

Message	Fix
`You uploaded an APK that is not signed with the upload certificate`	You used a different keystore. Use the original, or request an upload key reset in Play Console.
`Version code N has already been used`	Increase `versionCode` in `android/app/build.gradle` and rebuild.
`You uploaded a debuggable APK`	You built the debug variant. Use `bundleRelease`.
`Your app targets API level X`	Raise `targetSdk` (and `compileSdk`) to the level Play requires, then retest.
`Invalid Bundle. Missing Info.plist key`	Add the missing `NS*UsageDescription` string.
`ITMS-90717 Invalid App Store Icon`	The 1024px icon has an alpha channel — flatten it.
`No profiles for 'com.example.myapp' were found`	Register the App ID in the developer portal, then re-enable automatic signing.

Network requests fail only in the app

Relative URLs resolve against capacitor://localhost. Use absolute HTTPS URLs.
Your API must send CORS headers allowing capacitor://localhost and http://localhost, or use the native HTTP layer.
Plain HTTP is blocked in release builds on both platforms. Use HTTPS.
Cookie-based sessions are unreliable in the web view — use bearer tokens with the Preferences plugin.

Allowing the app origin on your API

const allowed = [
  "https://your-app.lovable.app",
  "capacitor://localhost",
  "http://localhost",
];

I lost my keystore

With Play App Signing enabled: Play Console → Setup → App integrity → request an upload key reset. Generate a new keystore, upload its certificate, and continue publishing the same listing.
Without Play App Signing: the listing cannot be updated. You must publish a new app with a new application ID and migrate users manually. This is why the backup step is non-negotiable.

Plugin installed but not available at runtime

bash

npm install @capacitor/the-plugin
npx cap sync            # required — installs the native side
# iOS additionally:
cd ios/App && pod install && cd ../..

"Plugin is not implemented on web" is expected in the browser — guard calls with Capacitor.isNativePlatform(). The same error on a device means cap sync did not run or the native build is stale.