Metro cannot resolve an import in a React Native app
Unable to resolve module ./Button from /Users/me/app/src/App.tsx:Short answer
Metro prints the import it could not resolve and the file that contains it. If the message lists candidate file names, the path or extension is wrong. If it says the name could not be found in node_modules, the package is missing from the folders Metro searches. Fix that one, then restart Metro with a clean cache.
Fix it fast
1Find out which cause you have
Read the first line and the lines after it. The first line names the import and the file that contains it. A list under None of these files exist means Metro tried file names and found none. A line saying the name could not be found within the project or in these directories means it searched node_modules folders. Open the named file and check that one import.
# first line of the error: Unable to resolve module ./Button from .../src/App.tsx: ls -la src/components grep -n "Button" src/App.tsx2Match what you see, then jump to its fix
- 1
The error lists candidate file names under None of these files exist, and the file you meant is not among them.The path, file name or extension is wrongFix - 2
The message says the package name could not be found within the project or in these directories, followed by node_modules.The package is not installed where Metro looksFix - 3
The file exists on disk, the path is right, and the import ends in an extension Metro is not configured to bundle, for example a custom data file.Metro does not know the file extensionFix - 4
The import points at a shared package or a sibling folder in a monorepo, and the path is right.The file is outside the project rootFix - 5
The import is correct, the file exists on disk, and the error survives every other change. It started after files were moved, renamed or generated.Metro still holds an outdated list of filesFix
- 1
What does the error look like?
Unable to resolve module ./Button from /Users/me/app/src/App.tsx:None of these files exist:some-package could not be found within the project or in these directories:
Cause 1 of 5
The path, file name or extension is wrong
1Check
A relative import is resolved against the folder of the file that contains it. Metro then tries the platform variants and the extensions it is configured for, for example Button.android.js, Button.native.js and Button.js. A typo, a moved file or a folder level that is off by one leaves nothing to match.
ls -la src/components
grep -rn "from './Button'" src/2Fix
Correct the import so it points at the real file, counted from the folder of the importing file. Check the spelling and the capital letters, and that the file was not moved or renamed.
// src/screens/Home.tsx, with the file at src/components/Button.tsx
import Button from '../components/Button';3Verify
Save the file. The error disappears and the app reloads.
npx react-native startConfirmed by metrobundler.dev
Cause 2 of 5
The package is not installed where Metro looks
1Check
For a package name, Metro looks in node_modules folders, starting at the importing file's folder and going up to the root. The message prints the directories it used. Check that the package is listed in package.json and present on disk.
grep -n "some-package" package.json
ls node_modules | grep -i some-package2Fix
Install the package where Metro looks. If your dependencies live outside the usual node_modules path, tell Metro with resolver.nodeModulesPaths, which it checks after all node_modules directories.
npm install some-package
// metro.config.js, only if the packages live elsewhere
resolver: { nodeModulesPaths: ['/path/to/shared/node_modules'] }3Verify
Restart Metro with the cache cleared and reload the app.
npx react-native start --reset-cacheConfirmed by metrobundler.dev
Cause 3 of 5
Metro does not know the file extension
1Check
The sourceExts setting defaults to js, jsx, json, ts and tsx. Setting it replaces that list, so a config that only adds one extension and forgets the defaults breaks the rest. Non-code files such as images belong to assetExts instead.
grep -n -B2 -A6 "sourceExts\|assetExts" metro.config.js2Fix
Add the extension to sourceExts, keeping the default values, or to assetExts when the file is an asset. The React Native docs recommend copying the defaults into your config and editing them there.
// metro.config.js: keep the defaults, then add the extension your file really has
const config = {
resolver: {
sourceExts: ['js', 'jsx', 'json', 'ts', 'tsx', 'yourext'],
},
};3Verify
Restart Metro with the cache cleared and open the screen that imports the file.
npx react-native start --reset-cacheConfirmed by metrobundler.dev
Cause 4 of 5
The file is outside the project root
1Check
Metro only knows files under the project root and the folders listed in watchFolders. A package next to the app, or a workspace package that is symlinked into node_modules, has to be inside that list.
grep -n "watchFolders" metro.config.js2Fix
List the folder that holds the shared code in watchFolders.
// metro.config.js
const path = require('path');
const config = {
watchFolders: [path.resolve(__dirname, '../shared')],
};3Verify
Restart Metro and open the screen again.
npx react-native start --reset-cacheConfirmed by metrobundler.dev
Cause 5 of 5
Metro still holds an outdated list of files
1Check
A file only counts as existing when Metro knows about it. resetCache clears the transformer cache and the file map cache on start-up.
ls -la src/components2Fix
Stop Metro and start it again with the cache removed.
npx react-native start --reset-cache3Verify
Reload the app. The error is gone and does not return on the next restart.
npx react-native startConfirmed by metrobundler.dev
How do I stop it coming back?
- Import with paths that match the real file name exactly, and keep one naming style for files.
- Spread the default sourceExts and assetExts into your config instead of replacing them.
- List every shared folder of a monorepo in watchFolders when you add it.
- Restart Metro with the cache cleared after you move or rename many files at once.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- QistLockA NestJS and React SaaS driving an Android Device Owner agent that locks financed phones when payments lapse.
- WorkforceA field app, an admin console and a self-hosted Node.js server for push and reconciliation.
Related fixes
Mobile apps
Gradle cannot run node in a React Native Android build
Process 'command 'node'' finished with non-zero exit value 1
The React Native Gradle plugin starts node for bundling.
3 causes, each with a fixMobile apps
Xcode cannot find node when building a React Native iOS app
[Warning] You need to configure your node path in the ".xcode.env" file environment.
Xcode runs the React Native bundle script without your terminal's PATH, so it needs a path to node.
4 causes, each with a fixMobile apps
pod install fails with 'Invalid Podfile file: no implicit conversion of nil into String'
[!] Invalid `Podfile` file: no implicit conversion of nil into String.
A React Native Podfile starts by running node to find react_native_pods.rb.
2 causes, each with a fixMobile apps
Xcode release build fails because Metro did not produce main.jsbundle
Your environment is misconfigured as Metro was not able to produce the bundle so your release application won't work!
The Xcode build phase asks Metro for a JavaScript bundle, and the build fails when that bundle was not written.
3 causes, each with a fixMobile apps
Android build stops at processDebugManifest in a React Native app
Manifest merger failed
processDebugManifest is the step that merges your AndroidManifest.xml with the manifests of every library.
2 causes, each with a fixMobile apps
Running pod on a React Native project fails with can't find gem cocoapods
can't find gem cocoapods (>= 0.a) with executable pod
The pod command exists, but the Ruby that is running it has no CocoaPods gem.
3 causes, each with a fix