DEV Community

RapidNative profile image Famitha M A
Famitha M A for RapidNative

Posted on Originally published at fami-blog.hashnode.dev

The 10 Most Common Expo Errors and How to Fix Them

#reactnative #expo #mobile #debugging

Most Expo errors fall into one of four layers: Metro couldn't bundle your code, JavaScript crashed at runtime, a native module is missing from the binary you're running, or the native build (Xcode or Gradle) failed. Naming the layer first is half the fix.

Here are the ten errors that come up most, what they mean and how to fix them. If yours isn't here, paste it into the free React Native & Expo Error Fixer and it will explain the cause and the fix.

Before anything else, two commands fix a surprising number of problems:

npx expo start --clear     # restart Metro with an empty cache
npx expo-doctor            # check your project for known issues
Enter fullscreen mode Exit fullscreen mode

1. Unable to resolve module 

Unable to resolve module ./components/Header from App.tsx:
./components/Header could not be found within the project
Enter fullscreen mode Exit fullscreen mode

Layer: Metro.

Why: the import path doesn't match a real file, the package isn't installed, or Metro is serving a stale cache after you moved or renamed something. A common one: the file is header.tsx but you import ./Header. macOS ignores case, but Linux CI and EAS Build don't.

Fix:

  • Check the path and the exact capitalisation.
  • For a package, install it with npx expo install <package> so you get the version that matches your SDK.
  • Restart with npx expo start --clear.
  • If you use path aliases like @/components, make sure they're set in tsconfig.json (Expo reads paths from it).

Paste your resolve error into the Error Fixer →

2. "main" has not been registered 

Invariant Violation: "main" has not been registered.
Enter fullscreen mode Exit fullscreen mode

Layer: JavaScript, at startup.

Why: the app's entry file never ran registerRootComponent, usually because something crashed while the first modules were loading, or Metro is running from the wrong folder (common in monorepos).

Fix:

  • Scroll up: the real error is usually printed just above this one. Fix that first.
  • Run npx expo start from the app's own folder.
  • If you changed the entry point, check the main field in package.json (expo-router/entry for Expo Router, or a file that calls registerRootComponent(App)).

3. Text strings must be rendered within a <Text> component 

Error: Text strings must be rendered within a <Text> component.
Enter fullscreen mode Exit fullscreen mode

Layer: JavaScript, at render.

Why: a raw string or number is sitting directly inside a View. The sneaky version is a conditional: {count && <Badge />} renders the number 0 when count is 0.

Fix:

  • Wrap text in <Text>.
  • Make conditionals return a boolean: {count > 0 && <Badge />} or {!!count && <Badge />}.
  • Look for stray characters, like a space or ; left between JSX tags.

4. VirtualizedLists should never be nested inside plain ScrollViews 

VirtualizedLists should never be nested inside plain ScrollViews
with the same orientation because it can break windowing and other functionality
Enter fullscreen mode Exit fullscreen mode

Layer: JavaScript (a warning, but a real performance problem).

Why: a FlatList inside a vertical ScrollView renders every row at once, so you lose the virtualization that makes lists fast.

Fix: remove the outer ScrollView and move the content above and below the list into ListHeaderComponent and ListFooterComponent. If you need several lists on one screen, use a SectionList.

5. Native module not found in Expo Go 

Error: Cannot find native module 'ExpoSomething'
Invariant Violation: TurboModuleRegistry.getEnforcing(...): 'RNSomething' could not be found.
Enter fullscreen mode Exit fullscreen mode

Layer: native module.

Why: Expo Go only contains the native code for the libraries bundled into it. A library with its own native code that isn't one of them will install fine and then crash at runtime.

Fix: create a development build, which is your own version of Expo Go with your libraries compiled in:

npx expo install expo-dev-client
eas build --profile development --platform ios   # or android
Enter fullscreen mode Exit fullscreen mode

If you're already on a development build and see this, you added the library after building. Rebuild.

6. Element type is invalid 

Element type is invalid: expected a string (for built-in components)
or a class/function (for composite components) but got: undefined.
Enter fullscreen mode Exit fullscreen mode

Layer: JavaScript.

Why: an import resolved to undefined. Almost always a default/named import mix-up: import Header from './Header' when the file does export function Header, or the other way around. Circular imports can cause it too.

Fix: match the import to the export (import { Header } from './Header' for a named export). The error's component stack tells you which component was undefined.

7. Too many re-renders 

Error: Too many re-renders. React limits the number of renders to prevent an infinite loop.
Enter fullscreen mode Exit fullscreen mode

Layer: JavaScript.

Why: state is set during render. The classic: onPress={setOpen(true)} calls the function immediately instead of passing it.

Fix:

  • Pass a function: onPress={() => setOpen(true)}.
  • Move state updates that depend on props into an event handler or a useEffect with the right dependencies.
  • The related "Maximum update depth exceeded" usually means a useEffect updates a value that's in its own dependency list.

8. Network request failed 

TypeError: Network request failed
Enter fullscreen mode Exit fullscreen mode

Layer: JavaScript, but the cause is usually the network setup.

Why: on a phone, localhost is the phone, not your computer. Other causes: plain http:// URLs, which Android blocks by default (and iOS App Transport Security restricts), or a server that isn't reachable from the device's network.

Fix:

  • Use your computer's LAN IP (for example http://192.168.1.20:3000) or a tunnel, and keep the phone on the same Wi-Fi.
  • Use https for anything outside local development.
  • Read the URL from an environment variable (EXPO_PUBLIC_API_URL) so dev and production can differ.

9. Package versions don't match your Expo SDK 

The following packages should be updated for best compatibility with the installed expo version:
  react-native-reanimated@3.x.x - expected version: ~3.y.y
Enter fullscreen mode Exit fullscreen mode

Layer: everywhere. Mismatched versions cause crashes at runtime and failures at build time.

Why: a library was installed with npm install instead of npx expo install, or the SDK was upgraded without updating its packages.

Fix:

npx expo install --fix
npx expo-doctor
Enter fullscreen mode Exit fullscreen mode

When upgrading the SDK, follow the release notes and run npx expo install expo@^<version> --fix.

10. EAS Build failed 

Gradle build failed with unknown error. See logs for the "Run gradlew" phase for more information.
Enter fullscreen mode Exit fullscreen mode

or on iOS, a failed "Install pods" or "Run fastlane" phase.

Layer: native build.

Why: the last line rarely says much. The real cause is further up in the phase that failed: often a version mismatch (see #9), a config plugin that needs a setting you haven't added, or credentials and signing.

Fix:

  • Open the failed phase in the EAS build page and search for the first error: line.
  • Run npx expo-doctor and fix what it reports.
  • Reproduce locally with npx expo prebuild --clean and then npx expo run:android or npx expo run:ios, which is much faster to iterate on than cloud builds.

Paste the failed build log into the Error Fixer →

A debugging routine that works for most of these

  1. Read the first error, not the last line. Red screens and build logs often end with something generic.
  2. Name the layer: Metro, JavaScript, native module or native build.
  3. Check how you run the app. Expo Go, a development build and a bare project behave differently.
  4. Clear caches with npx expo start --clear before deeper changes.
  5. Align versions with npx expo install --fix.

If you're stuck on an error that isn't in this list, the free React Native & Expo Error Fixer explains it in plain English: paste the error, choose where it happens and how you run the app, and it gives you the likely causes and the fix. It's made by RapidNative, where I work.

What's the Expo error that has cost you the most time? Drop it in the comments.

Top comments (0)