In the builder
| Message or symptom | Cause | Fix |
|---|---|---|
| "That ZIP couldn't be opened" | Not a standard ZIP (RAR/7z renamed, corrupted, password-protected) | Re-create it with your system's Compress / "Send to → Compressed folder" |
| "That ZIP is empty" | Only folders or only __MACOSX entries | Zip the files inside the folder |
| "No HTML page was found" | No .html file anywhere | Add index.html; for frameworks, zip the build output |
| Size limit message | Over 5 MB (free) / 18 MB (Pro) zipped | Treemap → compress images → remove junk |
| Preview opens the wrong page | Several candidate pages; the shallowest HTML file won | Put the real index.html at the root — root flattener |
| Content rejected | Page text matched a restricted category | Review the flagged content; contact support if it is a false positive |
The app shows a blank or broken screen
| Symptom | Likely cause | Fix |
|---|---|---|
| Completely blank white screen | Main script requested from /assets/… (root path) → 404 | Relative base (base: './' etc.) — configurator |
| Blank, or your 404 route, but assets load | History-mode router sees /web/index.html | Hash routing |
| Page works, then blank after pull-to-refresh | Reloading a history-mode deep URL | Hash routing, or turn off pull-to-refresh |
| Blank on old phones only | JS syntax newer than the WebView | Feature checker; lower the build target |
| Unstyled page | Stylesheet path wrong, wrong case, or from a CDN while offline | Case checker, CDN localizer |
| Some images missing | Letter case, or CSS url() resolved from the stylesheet's folder | Case checker; url(../img/x.webp) |
| Tiny, zoomed-out page | No viewport meta tag | <meta name="viewport" content="width=device-width, initial-scale=1"> |
Link to folder/ shows an error | Directory URLs are not expanded to index.html | Link to folder/index.html |
Runtime features
| Symptom | Likely cause | Fix |
|---|---|---|
| API calls fail, work on the website | CORS does not allow https://appassets.androidplatform.net | Allow the origin |
| Logged out on every request | SameSite=Lax session cookie not sent cross-site | Bearer token auth |
Google sign-in error disallowed_useragent | Google blocks OAuth in WebViews | Email/password, email link or phone sign-in |
| Camera / location does nothing | Permission not switched on, or denied by the user | Permissions step (Pro); handle the error callback |
| Share button throws | navigator.share is undefined in WebView | Feature-detect; copy-link fallback |
| Download / export button does nothing | No download manager in the app | Workarounds |
tel: / mailto: shows an error page | Free build loads them in the WebView | Pro hands them to the phone's apps |
| Service worker errors in the console | Registration is not supported for bundled files | Guard it with the hostname check |
Install and update
| Message | Cause | Fix |
|---|---|---|
| "App not installed" / "package conflicts with an existing package" | Same package name, different signing key | Uninstall the old app (data is lost) or sign with the original key |
| Update refused, older version already installed | New versionCode is not higher | Increase the version and rebuild |
| "For your security, your phone is not allowed to install unknown apps" | Sideloading not yet allowed for that browser/file manager | Tap Settings in the prompt and allow it once |
| "Blocked by Play Protect" | An unfamiliar developer signature | "More details → Install anyway"; publishing through Play removes the prompt for users |
| "There was a problem parsing the package" | Download incomplete, or file is an AAB | Re-download; install the APK, not the AAB |