> ## Documentation Index
> Fetch the complete documentation index at: https://docs.launchtoday.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common issues and how to fix them

## 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

```bash theme={null}
# 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

```bash theme={null}
cd apps/mobile/ios
rm -rf Pods Podfile.lock
pod install --repo-update
cd ..
pnpm ios
```

### Android Build Failures

```bash theme={null}
cd apps/mobile/android
./gradlew clean
cd ..
pnpm android
```

### Prisma Issues

```bash theme={null}
cd apps/api
pnpm prisma generate
pnpm prisma migrate dev
```

## Error Reference

<AccordionGroup>
  <Accordion title="'Unable to resolve module'">
    **Cause**: Missing dependency or incorrect import
    **Fix**:

    ```bash theme={null}
    pnpm install
    pnpm start --clear
    ```
  </Accordion>

  <Accordion title="'Network request failed'">
    **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
  </Accordion>

  <Accordion title="'Apple Sign-In failed'">
    **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
  </Accordion>

  <Accordion title="'state mismatch' (Google sign-in on Android)">
    **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`
  </Accordion>

  <Accordion title="'Database connection failed'">
    **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`
  </Accordion>

  <Accordion title="'Invalid hook call'">
    **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
  </Accordion>
</AccordionGroup>

## Next Steps

* [Incident Debugging](/essentials/incident-debugging)

## Getting Help

If you're still stuck:

1. **Search existing issues** on GitHub
2. **Check Expo documentation** at [docs.expo.dev](https://docs.expo.dev)
3. **Ask in the community** - Discord, GitHub Discussions
4. **Open an issue** with reproduction steps

<Tip>
  When reporting issues, include: - Error message (full stack trace) - Steps to
  reproduce - Platform (iOS/Android) and version - Expo SDK version
</Tip>