How do I reset Metro cache completely in Expo?
Run 'npx expo start -c' (the -c flag tells Expo to clear Metro's transform cache upon launch).
Metro Bundler Crash: Fixing 'Unable to Resolve Module' Errors
A Metro bundler 'Unable to resolve module' error occurs when Metro's module resolution algorithm cannot find an asset, package, or TypeScript file because of a stale packager cache, missing file extensions in metro.config.js, or duplicate peer dependencies in node_modules. Resetting the Metro cache with 'npx react-native start --reset-cache' resolves the error.
Common Symptoms & Error Signatures
- •Red Screen of Death: 'Unable to resolve module X from /src/App.tsx: None of these files exist'
- •Metro terminal halts on 'Bundling failed' with syntax or transformer error
- •Watchman throws: 'A non-recoverable condition has been detected: Connection refused'
- •SVGs or custom image extensions crash with 'Unexpected token < in JSON'
- •App works on iOS simulator but crashes on Android with module resolution failure
Root Causes & Diagnostic Checks
1. Stale Metro In-Memory Cache
Metro aggressively caches transformed JavaScript bytecode in temporary system directories. Renaming files or installing new packages without restarting Metro with --reset-cache leads to phantom missing file errors.
2. Missing Asset or SVG Transformer in metro.config.js
Importing .svg or custom data files without configuring react-native-svg-transformer in metro.config.js causes the bundler to treat binary assets as raw JavaScript code.
3. Duplicate React or Native Instances in Monorepos
In monorepos or nested workspaces, Metro may bundle two different copies of React or React Native, triggering fatal invalid hook calls or symbol redefinitions.
Targeted Code Solution
metro.config.js (Clean Resolver Setup)metro.config.js (Clean Resolver Setup)javascript
const { getDefaultConfig, mergeConfig } = require('@react-native/metro-config');
const defaultConfig = getDefaultConfig(__dirname);
const { assetExts, sourceExts } = defaultConfig.resolver;
const config = {
transformer: {
babelTransformerPath: require.resolve('react-native-svg-transformer'),
},
resolver: {
assetExts: assetExts.filter(ext => ext !== 'svg'),
sourceExts: [...sourceExts, 'svg', 'cjs'],
},
};
module.exports = mergeConfig(defaultConfig, config);Diagnostic & Action Matrix
| Metro Error Symptom | Root Cause | Fix Command |
|---|---|---|
| Unable to resolve module | Stale cache or bad import | npx react-native start --reset-cache |
| Watchman connection refused | Stale socket in /tmp | watchman watch-del-all |
| SVG syntax error (<) | Missing svg transformer | Configure react-native-svg-transformer in metro config |
| Duplicate React instance | Nested node_modules in monorepo | Add extraNodeModules in resolver config |
What I Change in the Codebase
metro.config.js
Ensure sourceExts includes required extensions (svg, ts, tsx, cjs).
watchman
Run 'watchman watch-del-all' to unfreeze file change detection.
node_modules
Remove node_modules and package-lock.json and run clean install if duplicate copies exist.
Production Verification
Verified in Voltix — Real-Time Solar Energy Intelligence
A React Native app using Skia, Reanimated, and custom SVG assets configured through optimized Metro pipelines.
Frequently Asked Questions
What does 'watchman watch-del-all' do?
Watchman is the tool React Native uses to monitor files for changes. Deleting existing watches clears corrupted file-socket locks.
Why does Metro fail on relative path imports like '@/components'?
You must configure path aliases in tsconfig.json and ensure your babel.config.js includes the 'babel-plugin-module-resolver' plugin.
Related Troubleshooting Guides
Need this resolved on your app?
If this error is blocking your release build or production pipeline, Syed Alijah Muhammad can diagnose and deploy a clean fix. Send the repository access, error trace, and platform details.