Skip to main content

​
Prerequisites

  • App and API running locally
  • Access to logs

​
Steps

  1. Identify the failing flow
  2. Apply the relevant fix below
  3. Re-run the flow and confirm

​
Common Issues

Quick fixes for the most common problems you’ll encounter.

​
Quick Fixes

​
Metro Bundler Issues

​
iOS Build Failures

​
Android Build Failures

​
Prisma Issues

​
Error Reference

Cause: Missing dependency or incorrect import Fix:
Cause: API not reachable from device Fix: 1. Check API is running (pnpm dev in apps/api) 2. Update API URL to your local IP (not localhost) 3. Check CORS settings include your device’s origin
Cause: Misconfigured Apple credentials Fix: 1. Verify bundle ID matches APPLE_CLIENT_ID 2. Check APPLE_PRIVATE_KEY is correctly formatted 3. Ensure Sign In with Apple is enabled in Apple Developer Console
Cause: OAuth started on one origin but the callback returned to another (common when mixing LAN URLs with ngrok).Fix:
  • If API uses ngrok: set both BETTER_AUTH_URL (API) and EXPO_PUBLIC_API_URL (mobile) to the same ngrok HTTPS origin
  • Ensure Google Console Authorized redirect URI matches exactly: https://YOUR_NGROK.ngrok-free.app/api/auth/callback/google
Cause: PostgreSQL not running or wrong credentials Fix: 1. Start PostgreSQL: docker-compose up -d or brew services start postgresql 2. Verify DATABASE_URL in .env 3. Run migrations: pnpm prisma migrate dev
Cause: React version mismatch or incorrect hook usage Fix: 1. Ensure only one React version: pnpm why react 2. Check hooks are only called at top level of components

​
Next Steps

​
Getting Help

If you’re still stuck:
  1. Search existing issues on GitHub
  2. Check Expo documentation at docs.expo.dev
  3. Ask in the community - Discord, GitHub Discussions
  4. Open an issue with reproduction steps
When reporting issues, include: - Error message (full stack trace) - Steps to reproduce - Platform (iOS/Android) and version - Expo SDK version