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

# Clear cache and restart
cd apps/mobile
pnpm start --clear

# Or nuclear option
rm -rf node_modules/.cache
watchman watch-del-all
pnpm start --clear

​
iOS Build Failures

cd apps/mobile/ios
rm -rf Pods Podfile.lock
pod install --repo-update
cd ..
pnpm ios

​
Android Build Failures

cd apps/mobile/android
./gradlew clean
cd ..
pnpm android

​
Prisma Issues

cd apps/api
pnpm prisma generate
pnpm prisma migrate dev

​
Error Reference

Cause: Missing dependency or incorrect import Fix:
pnpm install
pnpm start --clear
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