Skip to main content

​
Setup Issues

​
yarn install Fails

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

​
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

​
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

​
Social Login Issues

IssueSolution
No redirect after loginAdd [scheme]://auth/callback to Supabase URL Configuration
Nonce error with GoogleDisable “Skip Nonce Check” in Supabase Auth → Google
iOS Google not workingSet EXPO_PUBLIC_GOOGLE_IOS_CLIENT_ID and rebuild

​
RevenueCat / Payments

​
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

<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

yarn app:start --clear

​
Getting Help

  1. Expo Documentation
  2. Shipnative GitHub Issues
  3. Check Sentry dashboard for production errors
Debug tip: 
EXPO_DEBUG=true yarn app:ios