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

# Troubleshooting

> Common issues and solutions

## Setup Issues

### `yarn install` Fails

```bash theme={null}
rm -rf node_modules apps/*/node_modules yarn.lock
yarn install
```

### Environment Variables Not Loading

1. `.env` must be in `apps/app/` directory
2. Variables must start with `EXPO_PUBLIC_`
3. Restart Metro with cache clear:
   ```bash theme={null}
   yarn app:start --clear
   ```

***

## Metro Bundler

### Metro Won't Start

```bash theme={null}
rm -rf apps/app/.expo apps/app/node_modules/.cache
lsof -ti:8081 | xargs kill -9
yarn app:start --clear
```

### "Unable to resolve module"

Check `apps/app/tsconfig.json` has correct path mappings:

```json theme={null}
{
  "compilerOptions": {
    "paths": { "@/*": ["./app/*"] }
  }
}
```

Then clear Metro cache: `yarn app:start --clear`

***

## iOS Issues

### Simulator Won't Launch

```bash theme={null}
xcrun simctl list devices
xcrun simctl boot "iPhone 15 Pro"
yarn app:ios
```

### "Command PhaseScriptExecution failed"

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

### White Screen

Check console for JavaScript errors. Add `console.log` in `App.tsx` to debug.

***

## Android Issues

### Java Version Error

If you see an error like:

```
Error resolving plugin [id: 'com.facebook.react.settings']
> 25.0.1
```

**Cause**: Java 25 is too new. The `25.0.1` is your Java version, not a React Native version.

**Solution**: Use Java 17 (LTS):

```bash theme={null}
# Check available versions
/usr/libexec/java_home -V

# Build with Java 17
JAVA_HOME=$(/usr/libexec/java_home -v 17) yarn android

# Or set permanently in ~/.zshrc
export JAVA_HOME=$(/usr/libexec/java_home -v 17)
```

<Tip>
  Install Java 17 via Homebrew: `brew install --cask temurin@17`
</Tip>

### SDK Location Not Found

```bash theme={null}
export ANDROID_HOME=$HOME/Library/Android/sdk
export PATH=$PATH:$ANDROID_HOME/platform-tools
```

Or create `apps/app/android/local.properties`:

```
sdk.dir=/Users/YOUR_USERNAME/Library/Android/sdk
```

### Gradle Build Fails

```bash theme={null}
cd apps/app/android
./gradlew clean
cd ../../..
yarn app:android
```

***

## EAS Build Issues

### Yarn 4.x / Corepack Errors

If EAS Build fails with errors like:

* `EEXIST: file already exists`
* `ETARGET No matching version found for yarn@4.9.1`
* `Usage Error: This project is configured to use yarn` version mismatch

**This is already fixed in the boilerplate.** Shipnative bundles Yarn 4.x directly in `.yarn/releases/`, bypassing the corepack/npm conflict.

If you're on an older version, upgrade by pulling the latest changes:

```bash theme={null}
# Download and bundle yarn
mkdir -p .yarn/releases
curl -L -o .yarn/releases/yarn-4.9.1.cjs \
  https://repo.yarnpkg.com/4.9.1/packages/yarnpkg-cli/bin/yarn.js

# Update .yarnrc.yml to use bundled yarn
echo "yarnPath: .yarn/releases/yarn-4.9.1.cjs" >> .yarnrc.yml

# Commit it (the yarn binary is ~3MB)
git add .yarn/releases/ .yarnrc.yml
git commit -m "Bundle yarn 4.9.1 for EAS compatibility"
```

<Warning>
  Do NOT use `corepack: true` or `yarn: "4.x.x"` in eas.json. The bundled yarn approach handles everything automatically.
</Warning>

***

## Runtime Errors

### Navigation Errors

* Screen must be registered in `app/navigators/`
* Screen names are case-sensitive
* Check navigator nesting

### "Maximum update depth exceeded"

Infinite re-render loop. Don't call `setState` in render:

```typescript theme={null}
// BAD
const MyComponent = () => {
  const [count, setCount] = useState(0)
  setCount(count + 1) // Infinite loop!
  return <View />
}

// GOOD
const MyComponent = () => {
  const [count, setCount] = useState(0)
  useEffect(() => {
    setCount(c => c + 1)
  }, [])
  return <View />
}
```

### Authentication Loop

* Check auth state persistence in `useAuthStore`
* Don't navigate in render functions - use `useEffect`

***

## Social Login & Magic Link Issues

| Issue                             | Solution                                                                                                                            |
| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| No redirect after OAuth login     | Add `[scheme]://auth/callback` to Supabase URL Configuration                                                                        |
| Magic link redirects to wrong URL | Add `http://localhost:3000/auth/callback` (Vite) or `http://localhost:19006/auth/callback` (Expo web) to Supabase URL Configuration |
| Nonce error with Google           | Disable "Skip Nonce Check" in Supabase Auth → Google                                                                                |
| iOS Google not working            | Set `EXPO_PUBLIC_GOOGLE_IOS_CLIENT_ID` and rebuild                                                                                  |

***

## Deep Linking

### Testing Deep Links on iOS Simulator

<Warning>
  **Dev vs Production URL schemes are different!**

  Expo development builds register `exp+<scheme>` as the URL scheme, not just `<scheme>`.
</Warning>

```bash theme={null}
# For development builds (what you get with `yarn ios`)
xcrun simctl openurl booted "exp+yourscheme://profile"

# For production/release builds (EAS builds, TestFlight, App Store)
xcrun simctl openurl booted "yourscheme://profile"
```

To verify which scheme your app is using, check the built app's `Info.plist` - look for `CFBundleURLSchemes`.

### Deep Link Not Working

1. **Verify the scheme in `app.json`:**
   ```json theme={null}
   {
     "expo": {
       "scheme": "yourscheme"
     }
   }
   ```

2. **Check you're using the correct prefix:**
   * Dev build: `exp+yourscheme://`
   * Prod build: `yourscheme://`

3. **Ensure the path is configured in your navigation:**
   * Check `apps/app/app/navigators/linking.ts`

***

## RevenueCat / Payments

### "Invalid API Key" Error

If you see `[RevenueCat] There was a credentials issue. Invalid API Key.`:

**Cause**: Your `.env` has placeholder values like `EXPO_PUBLIC_REVENUECAT_IOS_KEY=your-ios-key`. These trigger the SDK with invalid credentials instead of mock mode.

**Solution**: Use empty values for mock mode:

```bash theme={null}
# In apps/app/.env
EXPO_PUBLIC_REVENUECAT_IOS_KEY=
EXPO_PUBLIC_REVENUECAT_ANDROID_KEY=
EXPO_PUBLIC_REVENUECAT_WEB_KEY=
```

<Note>
  The app now auto-detects placeholder values (starting with `your-`) and falls back to mock mode.
</Note>

### StoreKit "No Active Account" (iOS Simulator)

These errors are **expected and harmless**:

```
[StoreKit] Error Code=509 "No active account"
```

The simulator has no Apple ID. Purchases still work - you'll sign in with a sandbox account when testing.

### Purchase Fails

1. Verify API keys in `apps/app/.env`
2. Check products are configured in RevenueCat dashboard
3. Use sandbox/test accounts

***

## Performance

### Slow List Scrolling

```typescript theme={null}
<FlatList
  data={items}
  renderItem={renderItem}
  keyExtractor={(item) => item.id.toString()}
  removeClippedSubviews={true}
  maxToRenderPerBatch={10}
  initialNumToRender={10}
  windowSize={5}
/>
```

Use `useCallback` for `renderItem` and `React.memo` for list items.

***

## Development Tools

### TypeScript Not Working in VS Code

1. `Cmd+Shift+P` → "TypeScript: Restart TS Server"
2. Ensure using workspace TypeScript version
3. Reload window if needed

### Hot Reload Not Working

```bash theme={null}
yarn app:start --clear
```

***

## Supabase Issues

### Profile 404 Errors After Signup

If you see 404 errors in the browser console when fetching profile data after signup:

```
GET https://your-project.supabase.co/rest/v1/profiles?select=... 404
```

**This is usually expected and handled gracefully by the app.** The profile creation trigger may not have completed yet.

**If the errors persist:**

1. **Verify database schema is applied**
   ```bash theme={null}
   supabase db push  # Using migrations
   ```
   Or run the schema manually in SQL Editor

2. **Check RLS policies** - Ensure users can read their own profiles

3. **Verify the trigger is working** - The `handle_new_user()` function should auto-create profiles

4. **Configure redirect URLs** - Set to correct port (8081 for Expo, not 3000) in Supabase Dashboard → Authentication → URL Configuration

See `supabase/TROUBLESHOOTING.md` in your project for detailed solutions.

### TypeScript Errors with React Native

If you see errors like:

```
error TS6200: Definitions conflict with those in another file: BlobPart, FormData...
error TS2403: Variable 'require' must be of type 'Require'...
```

**This is already fixed in the boilerplate.** If you encounter it:

* Ensure `tsconfig.json` has `lib: ["esnext"]` (no "dom")
* Ensure `types: ["jest"]` (no "node")
* Remove `typeRoots` if present

### Migration Errors

If migrations fail with "already exists" errors:

```bash theme={null}
# Use IF NOT EXISTS in your migrations
CREATE TABLE IF NOT EXISTS public.my_table (...);

# Or mark migration as applied (if schema already matches)
supabase migration repair --status applied MIGRATION_ID
```

***

## Vercel Deployment Issues

### Missing Environment Variables on Vercel

If your Vercel deployment fails with:

```
Missing required environment variables: supabaseUrl, supabasePublishableKey
```

**This is already fixed in the boilerplate.** The `app.config.ts` includes an `extra` section that passes environment variables through to `Constants.expoConfig.extra` for web builds.

If you're on an older boilerplate version, see [Web Deployment → Troubleshooting](/deployment/web#troubleshooting) for the fix.

***

## Getting Help

1. [Expo Documentation](https://docs.expo.dev/)
2. [Shipnative GitHub Issues](https://github.com/shipnativeapp/shipnative/issues)
3. Check Sentry dashboard for production errors

**Debug tip:**

```bash theme={null}
EXPO_DEBUG=true yarn app:ios
```