Troubleshooting - Shipnative

Setup Issues

`yarn install` Fails

rm -rf node_modules apps/*/node_modules yarn.lock
yarn install

Environment Variables Not Loading

.env must be in apps/app/ directory
Variables must start with EXPO_PUBLIC_
Restart Metro with cache clear:
```
yarn app:start --clear
```

Metro Bundler

Metro Won’t Start

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:

{
  "compilerOptions": {
    "paths": { "@/*": ["./app/*"] }
  }
}

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

iOS Issues

Simulator Won’t Launch

xcrun simctl list devices
xcrun simctl boot "iPhone 15 Pro"
yarn app:ios

”Command PhaseScriptExecution failed”

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):

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

Install Java 17 via Homebrew: brew install --cask temurin@17

SDK Location Not Found

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

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:

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

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

Runtime 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:

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

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

Dev vs Production URL schemes are different!Expo development builds register exp+<scheme> as the URL scheme, not just <scheme>.

# 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

Verify the scheme in app.json:

{
  "expo": {
    "scheme": "yourscheme"
  }
}

Check you’re using the correct prefix:
- Dev build: exp+yourscheme://
- Prod build: yourscheme://
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:

# In apps/app/.env
EXPO_PUBLIC_REVENUECAT_IOS_KEY=
EXPO_PUBLIC_REVENUECAT_ANDROID_KEY=
EXPO_PUBLIC_REVENUECAT_WEB_KEY=

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

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

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

Performance

Slow List Scrolling

<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

Cmd+Shift+P → “TypeScript: Restart TS Server”
Ensure using workspace TypeScript version
Reload window if needed

Hot Reload Not Working

yarn app:start --clear

Supabase Issues

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:

Verify database schema is applied
```
supabase db push  # Using migrations
```
Or run the schema manually in SQL Editor
Check RLS policies - Ensure users can read their own profiles
Verify the trigger is working - The handle_new_user() function should auto-create profiles
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:

# 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 for the fix.

Getting Help

Expo Documentation
Shipnative GitHub Issues
Check Sentry dashboard for production errors

Debug tip:

EXPO_DEBUG=true yarn app:ios

Introduction

Getting Started

Core Features

Development

Deployment

Support

​Setup Issues

​yarn install Fails

​Environment Variables Not Loading

​Metro Bundler

​Metro Won’t Start

​”Unable to resolve module”

​iOS Issues

​Simulator Won’t Launch

​”Command PhaseScriptExecution failed”

​White Screen

​Android Issues

​Java Version Error

​SDK Location Not Found

​Gradle Build Fails

​EAS Build Issues

​Yarn 4.x / Corepack Errors

​Runtime Errors

​Navigation Errors

​”Maximum update depth exceeded”

​Authentication Loop

​Social Login & Magic Link Issues

​Deep Linking

​Testing Deep Links on iOS Simulator

​Deep Link Not Working

​RevenueCat / Payments

​”Invalid API Key” Error

​StoreKit “No Active Account” (iOS Simulator)

​Purchase Fails

​Performance

​Slow List Scrolling

​Development Tools

​TypeScript Not Working in VS Code

​Hot Reload Not Working

​Supabase Issues

​Profile 404 Errors After Signup

​TypeScript Errors with React Native

​Migration Errors

​Vercel Deployment Issues

​Missing Environment Variables on Vercel

​Getting Help

Setup Issues

`yarn install` Fails

Environment Variables Not Loading

Metro Bundler

Metro Won’t Start

”Unable to resolve module”

iOS Issues

Simulator Won’t Launch

”Command PhaseScriptExecution failed”

White Screen

Android Issues

Java Version Error

SDK Location Not Found

Gradle Build Fails

EAS Build Issues

Yarn 4.x / Corepack Errors

Runtime Errors

Navigation Errors

”Maximum update depth exceeded”

Authentication Loop

Social Login & Magic Link Issues

Deep Linking

Testing Deep Links on iOS Simulator

Deep Link Not Working

RevenueCat / Payments

”Invalid API Key” Error

StoreKit “No Active Account” (iOS Simulator)

Purchase Fails

Performance

Slow List Scrolling

Development Tools

TypeScript Not Working in VS Code

Hot Reload Not Working

Supabase Issues

Profile 404 Errors After Signup

TypeScript Errors with React Native

Migration Errors

Vercel Deployment Issues

Missing Environment Variables on Vercel

Getting Help