Skip to main content

Metro and Bundler Errors in React Native Apps

Metro serves the JavaScript bundle to your React Native app during development. Most Metro issues come from running the server in the wrong folder, stale cache, multiple Metro processes, missing dependencies, or a device that cannot reach the dev server.

Quick Answer​

Stop every Metro process, start Metro from the app folder that contains package.json, reset the cache, then rebuild the native app if it still points to an old bundle.

yarn start --reset-cache

In a second terminal:

yarn ios

or:

yarn android

Before You Debug Metro​

Confirm you are in the right app folder:

pwd
ls package.json ios android src

Then check dependency state:

corepack enable
yarn install

If the app package includes an .nvmrc, use it:

nvm use

Stop Existing Metro Processes​

If another project is using port 8081, the app may connect to the wrong bundle. Stop it:

lsof -ti :8081 | xargs kill -9

Then start Metro again from the current app folder:

yarn start --reset-cache

No Bundle URL Present​

This means the native app could not load the JavaScript bundle.

  1. Start Metro from the app folder.
  2. Reload the simulator or device.
  3. Rebuild the app if it was launched before Metro was started.
  4. For a physical device, confirm the device can reach the computer running Metro.
yarn start --reset-cache
yarn ios

or:

yarn start --reset-cache
yarn android

React Native Version Mismatch​

This usually means the native app connected to Metro from another project.

Fix it:

  1. Stop all Metro terminals.
  2. Kill port 8081.
  3. Start Metro from the current app package.
  4. Rebuild the native app.
lsof -ti :8081 | xargs kill -9
yarn start --reset-cache

Unable To Resolve Module​

Common causes:

  • dependencies were not installed;
  • Metro cache is stale;
  • the import path has the wrong case;
  • a package changed its exports field;
  • the app is being started from the wrong folder.

Start with:

yarn install
yarn start --reset-cache

If the error references a package subpath that is not exported, update the import site when it is app code. If the import comes from a third-party package, check whether the package has a compatible version already locked by the app package.

Watchman Recrawl Warning​

If Metro warns about Watchman recrawling the repository, reset the watch:

watchman watch-del .
watchman watch-project .

Then restart Metro:

yarn start --reset-cache

App Stays On Splash Screen​

If the native build succeeds but the app stays on the splash screen:

  • confirm Metro is running;
  • confirm the simulator/device can reach Metro;
  • check Metro terminal for bundling errors;
  • check device logs for a JavaScript exception;
  • check Firebase config if the first screen waits on backend data.

DevTools Uses Too Much Memory​

If opening React Native DevTools causes memory pressure, close DevTools and use Metro logs or device logs first. Debug the failing flow with smaller logs and avoid leaving multiple DevTools sessions open.

Verification​

Metro is healthy when:

  • yarn start --reset-cache starts from the correct app folder;
  • the app bundles ./index.js;
  • reload works from the simulator/device;
  • Metro does not report a version mismatch;
  • the same app opens after a native rebuild.

Next Steps​

FAQ​

Should I delete node_modules?​

Only after targeted fixes fail. Start with yarn install, yarn start --reset-cache, and stopping other Metro processes.

Should I delete the lockfile?​

No. The lockfile keeps the tested dependency versions stable. Deleting it can introduce unrelated upgrade problems.