Common Errors
Native Module Not Found
| Symptom | Likely cause | Fix |
|---|---|---|
| Module works in docs but not in app | Installed native package is not in current binary | Rebuild development client or preview build |
| Works in Expo Go docs but not your app | Expo Go includes a different native surface | Use development build and current SDK-compatible package |
| Metro reload does not help | Native code changed | Build and reinstall native binary |
Route Does Not Resolve
| Symptom | Likely cause | Fix |
|---|---|---|
| Link points to unexpected URL | Route group misunderstood | Remember (group) folders do not affect URL |
| Dynamic route params missing | Wrong file name or link shape | Check [id].tsx path and typed route errors |
| Tests discovered as routes | Test files under app/ | Move tests outside app/ |
Build Fails After Dependency Install
| Symptom | Likely cause | Fix |
|---|---|---|
| Android Gradle or iOS Pods fail | Package version not compatible with Expo SDK | Run npx expo install --check, check package docs and React Native Directory |
| Prebuild overwrote native changes | Manual edit was not durable | Move change into app config or config plugin |
| iOS only fails | Missing Apple tooling, pods, or iOS config | Use EAS cloud build or verify on macOS |
Update Does Not Appear
| Symptom | Likely cause | Fix |
|---|---|---|
| Device does not fetch update | Wrong branch/channel or incompatible runtime | Check build channel and update runtime version |
| Android updates but iOS does not | Platform-specific runtime mismatch | Inspect runtime versions per platform |
| Bad update still visible | Rollback not run or cached state | Run rollback, restart app, inspect update list |
Store Submission Blocks
| Symptom | Likely cause | Fix |
|---|---|---|
| Android submit fails | App not created in Play Console or service account missing | Complete Play setup and submit profile credentials |
| iOS upload succeeds but no release | TestFlight/App Store Connect still needs review work | Complete metadata, screenshots, privacy, build selection, review |
| Permission rejection | Vague permission copy or unjustified sensitive permission | Rewrite usage strings, add fallback, update store declaration |
Tip: When a mobile failure is unclear, separate JavaScript, Metro, native build, device install, runtime permission, and store submission layers. Debugging all layers at once wastes time.