Capacitor: white screen

Error text

Capacitor app opens to a white screen. Chrome inspect: Failed to load resource: net::ERR_FILE_NOT_FOUND / Uncaught SyntaxError: Unexpected token '<'

Cause

The WebView opens index.html, but JS and CSS files fail to load because of wrong paths, or the first script throws.

Step-by-step fix

1. Connect the phone over USB, open chrome://inspect on the computer and watch the WebView console.
2. If paths start with /, set base: "./" in the build config so they become relative.
3. Use a hash router, or set androidScheme: "https".
4. After each change run build and cap sync.
5. If you use a plugin, make sure its native side was built.

Example commands

chrome://inspect/#devices
npm run build && npx cap sync android
# vite.config: base: "./"
# capacitor.config: server: { androidScheme: "https" }

How to prevent it

Keep mobile build settings as a separate profile and test it on a phone each time.

Author and license: Nibras Code