# 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. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.buildnatively.com/getting-started/other-platform-integrations/replit/troubleshooting-guide.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.