Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Scan for outdated or missing drivers - takes under a minute3Repair Windows errors before they cause bigger problemsiTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
Metro’s “Unable to resolve module” error means it could not locate a file or package named in an import. The quickest route to a fix is to check the exact module name and the file importing it, then verify the path or app dependency before changing Metro settings or clearing caches.
Read the full error before changing anything
Note the unresolved module, the importing file, any searched paths or extensions, the platform, and where the failure occurs: local development, a production bundle, or a CI/EAS build. These details help distinguish a missing file from a dependency or environment problem.
If the name is an alias such as @src, check whether Metro knows how to resolve it—not only whether the editor or type checker does. If a package works locally but not in a workspace or build, check whether the app can access the dependency in that environment. Those differences are clues, not proof of a particular cause.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Check the import and the file or package
For a local file or alias
- Compare the import’s spelling and capitalization with the actual file name.
- For a relative path, confirm it is relative to the importing file and that the target exists in the checked-out project.
- For an alias, make sure the resolution is configured for Metro as well as any editor or type-checking tools.
For a package
- Check whether the package is declared in the app or workspace that imports it, rather than only at the repository root.
- Run the project’s package-manager install from the intended workspace or repository root, according to its workspace setup.
- For Expo SDK packages and compatible third-party libraries, prefer
npx expo install <package>where possible. Expo says this can select a version compatible with the project and warn about known incompatibilities. Check the library’s own installation steps too.
Expo’s library guidance also recommends checking platform compatibility. Some libraries need native configuration or code unavailable in Expo Go and may require a development build. That is different from Metro failing to find a JavaScript file; use a development build only when the library’s requirements point to one.
#1 Best Overall
Check versions and platform requirements
A package can be present yet incompatible with the project’s Expo SDK or React Native version. Check the library’s Expo compatibility guidance and the versions installed in the app. A server/device React Native version mismatch is a separate error class from a missing module; Expo lists it among common development errors.
If the unresolved import refers to a Node built-in such as zlib, check whether the dependency is intended to run in a React Native client bundle. A Node-oriented package may not be suitable for that environment. Do not assume that adding a browser polyfill is the right fix; use a client-compatible package or API when appropriate.
Rank #2
Check Metro configuration
React Native uses Metro to build JavaScript code and assets. In a React Native project, extend @react-native/metro-config or @expo/metro-config so the configuration retains the framework’s essential defaults. Custom resolver settings that replace or conflict with those defaults can interfere with module resolution.
For an Expo monorepo, check the project’s installed SDK version before editing metro.config.js:
Rank #3
Expo SDK 52 and later
Expo documents automatic monorepo Metro configuration for SDK 52 and later when using expo/metro-config. If the config still overrides watchFolders, resolver.nodeModulesPath, resolver.extraNodeModules, or resolver.disableHierarchicalLookup based on older guidance, remove those legacy overrides and run npx expo start --clear once.
Before Expo SDK 52
Older SDKs may need manual Metro configuration to watch code across the repository and search relevant workspace node_modules locations. Follow the monorepo instructions for the project’s installed SDK rather than applying newer automatic-configuration assumptions to an older setup.
Rank #4
Check workspace dependencies and duplicates
Confirm the package manager recognizes the workspace and that the importing app declares the dependency it uses. Expo documents workspace setups for npm, pnpm, Yarn, and Bun. Hoisting can make an undeclared dependency appear available locally, leaving the project fragile or failing in a clean install or another environment.
Recommended Free Tools
Use your package manager’s dependency inspection command to check for duplicate versions of React, React Native, and native modules. Expo says duplicate React Native versions in a monorepo are unsupported, while duplicate React versions in one app cause runtime errors.
Isolated dependency installs require SDK-specific care: Expo supports them starting with SDK 54. Its monorepo guidance recommends disabling isolated dependencies on SDK 53 when native build errors or dependency conflicts arise. If a pnpm isolated install itself causes resolution problems, Expo documents nodeLinker: hoisted as a fallback.
Clear Metro caches after fixing the underlying issue
Cache clearing can help when stale or corrupted state remains plausible after paths, dependencies, and configuration are correct. It cannot install an absent package or repair an incorrect import.
- Expo CLI:
npx expo start --clear - React Native CLI with Yarn:
yarn start -- --reset-cache - React Native CLI with npm:
npm start -- --reset-cache
Expo’s broader macOS/Linux cleanup also includes watchman watch-del-all, clearing $TMPDIR/haste-map-* and $TMPDIR/metro-cache, and reinstalling dependencies. In Yarn workspaces, removing node_modules may be necessary in each workspace. Reinstall dependencies after deleting them.
Metro’s troubleshooting guidance separately recommends clearing Watchman watches, reinstalling dependencies, passing --reset-cache (or setting resetCache: true in Metro config), and removing ${TMPDIR:-/tmp}/metro-*. Use cleanup commands suited to your operating system and package-manager layout; do not wipe every cache as the first response to an obvious typo or missing dependency.
Quick Recap
Match the symptom to the next check
- A relative path or local alias is unresolved: verify the target file, capitalization, path, and Metro’s alias configuration.
- A package name is unresolved: check that the importing app or workspace declares and can access it, then install a compatible version.
- The package exists but versions or platforms differ: check Expo SDK, React Native alignment, and the library’s platform and native-code requirements.
- The failure is specific to a monorepo, clean install, or build environment: verify workspace recognition, dependency declarations, SDK-specific Metro setup, duplicate packages, and legacy resolver overrides.
- A Node built-in is unresolved in app code: check whether the package is meant for a React Native client before reaching for a polyfill.
- Paths, installs, and configuration check out: reset Metro’s cache and retry.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
