Troubleshooting Guide

Here’s a detailed list of the most common issues you may encounter when turning your Replit project into a mobile app with BuildNatively, along with explanations and fixes.

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.