Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Flutter and app store releases

Metro cannot resolve an import in a React Native app

ErrorUnable 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.

  • Applies to React Native 0.8x, Metro 0.8x, Node.js 22
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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.tsx
  2. 2Match what you see, then jump to its fix

    1. 1The 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. 2The 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. 3The 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. 4The 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. 5The 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

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 start

Confirmed by metrobundler.dev

Did this fix it?

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-package

2Fix

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-cache

Confirmed by metrobundler.dev

Did this fix it?

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.js

2Fix

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-cache

Confirmed by metrobundler.dev

Did this fix it?

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.js

2Fix

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-cache

Confirmed by metrobundler.dev

Did this fix it?

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/components

2Fix

Stop Metro and start it again with the cache removed.

npx react-native start --reset-cache

3Verify

Reload the app. The error is gone and does not return on the next restart.

npx react-native start

Confirmed by metrobundler.dev

Did this fix it?

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:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.