Troubleshooting Fix common setup, runtime, build, and release issues.
Most Expo template issues come from one of four places: Metro cache, public env
values being inlined into the bundle, using Expo Go for a native-module feature,
or mismatched variant identifiers.
Start with the checks the template already expects:
pnpm typecheck pnpm lint pnpm dev pnpm dev runs expo start -c -p 3000, so it clears Metro cache and uses the
documented development port.
For a deeper local reset:
watchman watch-del-all rm -rf .expo pnpm dev Use pnpm clean only when you intentionally want to remove node_modules too.
Symptom Likely cause Fix Metro starts but the app shows stale copy/config Env values are inlined and the old bundle is still running Stop Metro, restart with pnpm dev, then reload the app Port 3000 is busy Another dev server is running Stop the other process or run expo start -c -p <port> manually iOS simulator does not appear Xcode simulator runtime is missing or not installed Open Xcode, install a simulator runtime, then rerun pnpm ios Android emulator fails to boot Android Studio SDK or JAVA_HOME is not configured Open Android Studio, install SDK/platform tools, and verify the emulator outside Expo File watcher behaves oddly Watchman cache is stale Run watchman watch-del-all and restart Metro
Symptom Likely cause Fix Supabase client errors at startup Missing EXPO_PUBLIC_SUPABASE_URL or EXPO_PUBLIC_SUPABASE_ANON_KEY Copy .env.example to .env.local, set both values, and restart Metro Provider remains disabled after setting a key The old JS bundle still has the previous env Restart Metro with cache clear; for EAS builds, create a new build Secret appears in the app bundle A server secret was put in EXPO_PUBLIC_* Rotate the secret and move it to Supabase Edge secrets, EAS secrets, or CI secrets Preview build uses production backend Variant-specific env was not set for the EAS profile Check EAS env values and APP_VARIANT for the profile
EXPO_PUBLIC_* values are public. Do not put service-role keys,
REVENUECAT_WEBHOOK_AUTH, APNs keys, or SENTRY_AUTH_TOKEN in them.
Symptom Likely cause Fix Purchases say they are not configured or unavailable react-native-purchases needs a native buildUse eas build --profile development --platform ios or Android equivalent Google Sign-In button fails Native Google Sign-In module and OAuth clients require a native build Configure Google client IDs and test in a dev or store build Native module cannot be found Expo Go does not bundle that native dependency Install and open the template's development client Push token is null Simulator, web, denied permission, or no real device token Test on a physical device and request notification permission Haptics, biometrics, or ATT no-op Platform fallback or unsupported hardware Test on supported iOS/Android hardware
Expo Go is still useful for early UI and web-compatible flows. Use development
builds for purchases, Google Sign-In, realistic notifications, biometric lock,
and store-review behavior.
Symptom Likely cause Fix Email verification opens a dead end Redirect URL is not allowed in Supabase Auth settings Add the active scheme callback for the current variant OAuth returns to the wrong app Bundle/scheme variant mismatch Use soar-starter-expo-dev, soar-starter-expo-preview, or soar-starter-expo consistently Session disappears on native SecureStore write failed or stored session chunks are stale Sign out/in, clear app data, and check lib/secure-store-chunked.ts if custom session data grew Signed-out users can see public screens This is intentional Protect actions with SignInGate or require auth in the route you add
Symptom Likely cause Fix Google button says not configured Missing EXPO_PUBLIC_GOOGLE_WEB_CLIENT_ID Add the web client ID used by Supabase Google provider Native Google flow fails on iOS Missing or wrong EXPO_PUBLIC_GOOGLE_IOS_CLIENT_ID Create an iOS OAuth client for the bundle ID being tested Android sign-in fails after release signing SHA-1 fingerprint mismatch in Google Cloud Add fingerprints for the debug, upload, or Play signing certificate you use Supabase rejects the token Google provider is not configured in Supabase Enable Google provider and use the same OAuth client setup
Symptom Likely cause Fix Todos or uploads fail with RLS errors Migrations were not applied Run supabase db push against the linked project TypeScript does not know a new table types/database.ts is staleSet SUPABASE_PROJECT_ID and run pnpm gen:types Upload sample says env is missing Storage helper reads the public Supabase pair Set EXPO_PUBLIC_SUPABASE_URL and EXPO_PUBLIC_SUPABASE_ANON_KEY Avatar upload fails but sample upload works Avatar uses a separate bucket path from sample uploads Create or verify the avatar bucket and policies required by your profile flow
Symptom Likely cause Fix Paywall shows no packages No current offering, products are not attached, or store metadata is incomplete Fix the RevenueCat offering and wait for store sync Purchases work in RevenueCat but app stays free Supabase subscriptions row is missing or not entitled Check webhook URL, REVENUECAT_WEBHOOK_AUTH, and function logs Development build cannot load products Bundle/package ID does not match store product setup Create products for the active variant or test the production ID Android purchase does not unlock entitlement The shipped webhook ignores PLAY_STORE Extend providerForStore() and the billing provider enum before relying on Android entitlements
Symptom Likely cause Fix Permission request works but no server push arrives Token is not persisted by the template Add a device_tokens table and save the Expo push token send-test-push failsThe optional function queries a table the template does not ship Add the table and registration path, or replace it with Expo push API sending Android notifications have odd behavior Notification channel setup changed or permission was denied Recheck lib/notifications.tsx and Android POST_NOTIFICATIONS permission Web has no real push flow Current implementation is native-focused Add a separate web push implementation if your product needs it
Symptom Likely cause Fix Custom scheme link opens nothing Wrong variant scheme Use soar-starter-expo-dev://, soar-starter-expo-preview://, or soar-starter-expo:// Universal/App Link does not open the app AASA or assetlinks file is missing or not verified Host the required files for EXPO_PUBLIC_LINKING_DOMAIN and rebuild native apps URL opens the app but not the route Route is not in the allow-list resolver Update lib/deep-links.ts for your product routes Notification tap goes nowhere Notification payload lacks a supported URL Send a URL that resolveDeepLinkHref() accepts
Symptom Likely cause Fix OTA update does not arrive Channel or runtime version mismatch Publish to the build's channel and app version Native change is missing after OTA OTA cannot ship native modules, permissions, or config plugin changes Create a new EAS build Store build has wrong app name or bundle ID APP_VARIANT was not productionCheck the production profile env and rebuild Sentry sourcemaps are missing SENTRY_AUTH_TOKEN was not available during uploadStore it as an EAS or CI secret and run the sourcemap upload step Version gate test never appears Env update config was not in the running bundle Restart Metro or rebuild, or use APP_UPDATE_CONFIG_URL for remote overrides
