Metro’s “Unable to resolve module” error means it cannot find a file or package referenced by an import. The quickest route to a fix is to identify the exact module name and importing file, then check the import path and the app workspace’s dependencies. Only investigate SDK compatibility, monorepo layout, or Metro configuration when those first checks point there; clear caches after correcting the underlying issue.
What the error tells you
React Native uses Metro to build JavaScript code and assets, so a failed resolution means Metro could not locate something an import refers to. The message alone does not identify why. Read the complete error and note:
As an Amazon Associate I earn from qualifying purchases.
- The exact module name, including capitalization and punctuation.
- The file containing the import.
- Any searched directories or file extensions shown in the output.
- Whether the failure is for a particular platform, during local development, or in a production or CI/EAS build.
- Whether the same code works outside a clean install or outside the app workspace.
These details distinguish a missing local file from an absent package, an alias Metro does not know about, a workspace-resolution problem, or an import that is unsuitable for a React Native client bundle.
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Check the import before changing configuration
For a relative path or alias
- Compare the import with the actual file name, directory, capitalization, and extension in the checked-out project.
- Remember that a relative path is resolved from the file doing the importing, not from the repository root.
- If the import uses an alias such as
@src, confirm that Metro is configured to understand it. An editor or type checker accepting an alias does not prove Metro or the build environment can resolve it.
For a package import
Check the app or workspace’s package.json and confirm the package is actually available in that workspace’s dependency graph. A dependency present only at the repository root may not be available to the app, depending on the workspace and package-manager layout. Install from the intended workspace or repository root using that project’s package manager.
#1 Best Overall
For Expo SDK packages and compatible third-party libraries, Expo recommends npx expo install <package> where possible. It can select a version compatible with the project and warn about known incompatibilities. Follow the library’s own installation requirements as well. Expo SDK reference
Check version and platform requirements
A package can exist and still be incompatible with the project’s Expo SDK, React Native version, or target platform. Check the library’s documented platform support and the version guidance for the project’s SDK before changing Metro settings.
Some libraries need native code or native project configuration that is not included in Expo Go; those may require a development build. That is different from Metro being unable to find a JavaScript module. Use a development build only when the package’s requirements or the actual error indicate that native support is the issue. Expo: Using libraries
Rank #2
Check Metro configuration
Custom Metro configuration can interfere with module resolution if it replaces or conflicts with framework defaults. React Native advises extending @react-native/metro-config or @expo/metro-config in React Native projects, because these packages provide essential defaults. React Native: Metro
Before editing a monorepo’s metro.config.js, identify the installed Expo SDK: the appropriate setup depends on the SDK version.
Expo SDK 52 and later
With expo/metro-config, Expo automatically configures Metro for monorepos. If the config still contains legacy overrides for watchFolders, resolver.nodeModulesPath, resolver.extraNodeModules, or resolver.disableHierarchicalLookup, remove the obsolete overrides in line with the current guide, then run npx expo start --clear once. Expo: Work with monorepos
Rank #3
Expo SDK versions before 52
Older SDKs may need manual Metro configuration so the bundler watches code across the repository and searches the relevant workspace node_modules locations. Follow the monorepo instructions for the project’s installed SDK rather than applying SDK 52-and-later assumptions to an older setup. Expo: Work with monorepos
Inspect workspace dependencies and duplicates
In a monorepo, verify that the package manager recognizes the workspace and that the app declares the dependency it imports. Hoisting can make an undeclared dependency appear to work locally, then fail in a clean install or build. Expo’s monorepo guide covers npm, pnpm, Yarn, and Bun layouts; use its guidance for the project’s package manager. Expo: Work with monorepos
Use the package manager’s dependency-inspection command to look for duplicate React Native, React, and native-module versions. Expo says duplicate React Native versions in a monorepo are unsupported, and duplicate React versions in one app cause runtime errors. These conflicts can accompany resolution or build problems, but do not assume they are the cause without inspecting the dependency tree.
Rank #4
Isolated dependency guidance also depends on SDK version: Expo supports isolated dependencies from SDK 54; its guide recommends disabling them on SDK 53 when native build errors or dependency conflicts arise. If an isolated pnpm installation itself is causing resolution problems, Expo documents nodeLinker: hoisted as a fallback. Apply only the advice matching the project’s SDK and package-manager setup. Expo: Work with monorepos
Recognize Node-only imports
If the unresolved name is a Node built-in such as zlib, check whether the dependency is intended to run inside a React Native app. A package designed for Node may rely on built-ins unavailable in the client bundle. Do not assume that adding a browser polyfill is the right fix; choose a client-compatible package or API when the dependency is not meant for React Native. Expo issue reports show examples of this error shape, but do not establish one universal remedy. Expo issue #30440
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Clear out junk files and repair common Windows errorsFree Scan →Clear Metro and Watchman caches after correcting the cause
Cache resets can help when stale or corrupt state remains plausible, but they cannot install an absent package, repair a misspelled path, or correct an incompatible Metro configuration. Start with the least disruptive applicable command:
- 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 clearing Watchman watches with watchman watch-del-all, removing temporary Haste and Metro cache data, and reinstalling dependencies. Metro separately documents clearing Watchman watches, reinstalling dependencies, restarting with --reset-cache (or setting resetCache: true in Metro configuration), and removing temporary Metro files. These broader steps are more disruptive; deleting node_modules means dependencies must be installed again, and Yarn workspaces may have a node_modules directory in more than one workspace. Follow the commands and shell details in the official guides rather than deleting files blindly. Expo: Clear bundler caches on macOS and Linux · Metro: Troubleshooting
Match the symptom to the next check
| What the error or setup suggests | Next check |
|---|---|
| The unresolved name is a relative path or local alias | Confirm the target exists, spelling and case match, and any alias is configured for Metro as well as the editor or type checker. |
| The unresolved name is a package | Check the app workspace’s dependencies and install the package in the correct workspace at a compatible version. |
| The package is installed but incompatible behavior or version errors appear | Check Expo SDK and React Native alignment, and the library’s platform and native requirements. |
| The package exists elsewhere in a monorepo or only works locally | Check workspace declarations, SDK-specific Metro setup, package-manager layout, duplicate dependencies, and legacy resolver overrides. |
| The module is a Node built-in | Verify that the dependency is intended for a React Native client bundle; select a client-compatible alternative if it is not. |
| Paths, dependencies, and configuration look correct, but resolution still appears stale | Use the documented Expo or Metro cache reset for the project’s CLI. |
Related errors that need a different diagnosis
A server/device React Native version mismatch is a separate development error, not the same thing as a missing import. If the message refers to versions differing between the running server and device, follow Expo’s guidance for that error rather than treating it as a path or cache failure. Expo: Common development errors
Quick Recap
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.
