Join our community 🔥

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.

PreviousIntegrationNextReleases

Last updated

Was this helpful?