> For the complete documentation index, see [llms.txt](https://docs.buildnatively.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.buildnatively.com/getting-started/other-platform-integrations/replit/troubleshooting-guide.md). # Troubleshooting Guide ### 1. Login & Authentication Issues #### 1.1 My login opens in Safari/Chrome instead of inside the app * **Why it happens:** Social login (Google, Apple, Facebook) requires deep links (Universal Links/App Links) to bring users back to the app. * **How to fix:** 1. Enable **Deep Links** in BuildNatively. 2. Turn on **Social Auth** in the Features section. 3. Rebuild your app. *** #### 1.2 My email/password login fails in the app but works in Replit * **Why it happens:** Cookies or session handling may break if redirects jump across domains. * **How to fix:** * Keep login pages on your main Replit domain (or custom domain). * Avoid sending users to another subdomain for authentication. * Make sure your entire app runs on **HTTPS**. *** #### 1.3 I get stuck after login (blank page or endless spinner) * **Why it happens:** Post-login redirects may point to a popup instead of a full page. * **How to fix:** * In Replit, create a dedicated page (like `/dashboard`) for the post-login redirect. * Update your login flow to redirect there. *** ### 2. Payments & Checkout Issues #### 2.1 Stripe/PayPal checkout doesn’t work in the app * **Why it happens:** Payment providers often require the phone’s browser to handle checkout securely. * **How to fix:** * Mark checkout pages as **external** in BuildNatively. * This ensures they open in Safari/Chrome and complete successfully. *** #### 2.2 Apple/Google rejected my app because of payments * **Why it happens:** Stores require In-App Purchases for **digital goods and subscriptions**. * **How to fix:** * For digital content: enable **In-App Purchases** (RevenueCat) in BuildNatively. * For physical goods or real-world services: you may keep Stripe/PayPal. *** ### 3. Push Notifications & Deep Links #### 3.1 Notifications arrive but nothing happens when tapped * **Why it happens:** The notification didn’t include a deep link. * **How to fix:** * Add a URL in the notification payload (e.g., `/messages/123`). * Make sure that URL exists and works in your Replit app. *** #### 3.2 Notifications open the wrong page * **Why it happens:** The link in the notification doesn’t match your Replit routes. * **How to fix:** * Double-check that the link exactly matches your app’s route structure. *** #### 3.3 Notifications don’t show up at all * **Why it happens:** Push service setup is incomplete. * **How to fix:** * Confirm push is enabled in BuildNatively. * Upload correct configuration (OneSignal/Firebase). * Rebuild your app and test again. *** ### 4. Layout & Display Issues #### 4.1 Some pages look broken or cut off on small screens * **Why it happens:** The Replit layout isn’t mobile-optimized. * **How to fix:** * Adjust your CSS in Replit for responsive design. * Stack elements vertically instead of side-by-side. *** #### 4.2 iOS zooms in too much on forms * **Why it happens:** iOS zooms when input fields have small font sizes. * **How to fix:** * In Replit, set input font sizes to **at least 16px**. *** #### 4.3 Scrolling feels broken * **Why it happens:** Nested scrollable areas or large fixed sections can conflict with native scrolling. * **How to fix:** * Simplify layouts and avoid multiple nested scroll containers. *** ### 5. Links & Navigation #### 5.1 External links don’t work (YouTube, Calendly, Docs) * **Why it happens:** By default, BuildNatively treats all links as internal. * **How to fix:** * Add these domains as **external links** in BuildNatively so they open in the device’s browser. *** #### 5.2 Internal links reload the app instead of navigating * **Why it happens:** The link points to a different domain or subdomain. * **How to fix:** * Keep all internal navigation on your main Replit domain. *** #### 5.3 Bottom bar tabs don’t load correctly * **Why it happens:** Each tab must point to a valid page inside your app. * **How to fix:** * Double-check that tab URLs match real Replit routes. *** ### 6. Media, Camera & Files #### 6.1 Camera or microphone don’t work * **Why it happens:** Permissions weren’t set. * **How to fix:** * Enable **Camera** or **Microphone** in BuildNatively. * Add clear permission descriptions. * Rebuild the app. *** #### 6.2 File uploads fail * **Why it happens:** Upload endpoints may be insecure or unstable. * **How to fix:** * Ensure all upload routes use **HTTPS**. * Test uploads on full pages instead of popups. *** #### 6.3 Images and videos load too slowly * **Why it happens:** Media files are too large. * **How to fix:** * Compress images/videos before uploading to Replit. *** ### 7. Location & Permissions #### 7.1 Location services don’t work * **Why it happens:** The feature wasn’t enabled. * **How to fix:** * Enable **Geolocation** in BuildNatively. * Add a clear permission description. * Rebuild the app. *** #### 7.2 Apple rejected my app for missing permission text * **Why it happens:** Apple requires a description for each permission. * **How to fix:** * Add clear explanations in BuildNatively. * Examples: * “We use your location to find nearby events.” * “We use your contacts to help you invite friends.” *** ### 8. Publishing Issues #### 8.1 Apple rejected my app as “just a website” * **Why it happens:** Apple expects apps to offer **native features**. * **How to fix:** * Add push notifications, deep links, or other native features. * Rebuild and resubmit. *** #### 8.2 My icon or splash screen didn’t update * **Why it happens:** Old assets were cached. * **How to fix:** * Upload new assets in BuildNatively. * Rebuild your app. * Uninstall old versions from your phone before testing. *** #### 8.3 App loads slowly on startup * **Why it happens:** The homepage in Replit is too heavy. * **How to fix:** * Optimize large images/videos. * Remove unnecessary scripts. * Keep the homepage simple. *** ### 9. Preview vs. Full Build #### 9.1 Features don’t work in the Preview App * **Why it happens:** Some native features aren’t supported in Preview. * **How to fix:** * Use Preview for layout and navigation checks. * Do a full build to test push, deep links, social login, and purchases. *** ### 10. General Tips * Always use **HTTPS** everywhere. * Create **stable routes** for login, profile, checkout, and dashboard. * Mark checkout and third-party services as **external**. * Add clear **permission descriptions** before submitting to app stores. * Optimize Replit content for mobile. * Rebuild your app whenever you change **native settings**. *** ### 11. App Store & Play Store Rejections #### 11.1 “Just a website” rejection * **Fix:** Add native features (push, deep links, sharing, camera, location). #### 11.2 Payment policy rejection * **Fix:** Use In-App Purchases for digital goods/subscriptions. Stripe/PayPal only for physical goods. #### 11.3 Missing permission descriptions * **Fix:** Add clear, user-friendly explanations in BuildNatively. #### 11.4 Broken or poor navigation * **Fix:** Test all links. Mark external ones correctly. #### 11.5 Performance issues * **Fix:** Optimize Replit homepage and assets. #### 11.6 Insufficient content * **Fix:** Fill your app with real, working content before submission. #### 11.7 Privacy or policy rejection * **Fix:** Add a **Privacy Policy** page in your Replit app and link it in store listings. *** ### Quick Fix Checklist * ✅ HTTPS everywhere. * ✅ One domain for internal pages. * ✅ Stable URLs for login, profile, checkout. * ✅ External links configured correctly. * ✅ Permission descriptions added. * ✅ Push, deep links, and purchases set up if needed. * ✅ Layout tested on real phones. * ✅ Rebuilt after any native changes.