Maaz Zindani

Loading the index…

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

Xcode release build fails because Metro did not produce main.jsbundle

Errorerror: File .../main.jsbundle does not exist.

Short answer

The Xcode build phase asks Metro for a JavaScript bundle, and the build fails when that bundle was not written. Read the lines above the error in the Xcode build log. The usual causes are Xcode not finding Node.js, the Hermes compiler missing from Pods, or a wrong entry file.

  • Applies to React Native 0.76, Xcode 26, Node.js 22, CocoaPods
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Open the failed build in the Xcode Report navigator and read the Bundle React Native code and images step from the top. The first error there is the real one. You can also try the build from Terminal to see the same log.

    # Xcode: Product > Scheme > Edit Scheme > Run > Build Configuration = Release, then build and open the Report navigator
  2. 2Match what you see, then jump to its fix

    1. 1command not found: node, or the script runs a different Node than your shellXcode cannot find Node.jsFix
    2. 2Hermes is enabled but the hermesc binary could not be foundThe Hermes compiler (hermesc) is not in PodsFix
    3. 3No bundle is produced and your entry file is not index.js or index.ios.jsThe entry file is not where the script looksFix

What does the error look like?

  • error: File .../main.jsbundle does not exist.
  • Your environment is misconfigured as Metro was not able to produce the bundle so your release application won't work!
  • error: Hermes is enabled but the hermesc binary could not be found

Cause 1 of 3

Xcode cannot find Node.js

1Check

Xcode does not read your shell setup the way Terminal does. Since React Native 0.69 the project has ios/.xcode.env, which exports the Node binary the build phase uses.

cat ios/.xcode.env
which node

2Fix

Make NODE_BINARY point to the Node.js you use. If you load nvm in ~/.zshrc, move its init lines to ~/.zshenv so non-interactive shells get them.

# ios/.xcode.env
export NODE_BINARY=$(command -v node)

3Verify

Clean and build the Release configuration again.

# Xcode: Product > Clean Build Folder, then build the Release configuration

Confirmed by reactnative.dev

Did this fix it?

Cause 2 of 3

The Hermes compiler (hermesc) is not in Pods

1Check

With Hermes on, the script compiles the bundle with hermesc from the installed hermes-engine pod. The script's own hint is to run pod install again.

ls ios/Pods | grep -i hermes

2Fix

Reinstall the pods from the ios folder, using Bundler if the project has a Gemfile.

cd ios
bundle exec pod install

3Verify

Build the Release configuration again from Xcode (Product > Build with the scheme set to Release); the hermesc error is gone.

ls ios/Pods | grep -i hermes

Confirmed by raw.githubusercontent.com

Did this fix it?

Cause 3 of 3

The entry file is not where the script looks

1Check

Unless ENTRY_FILE is set, the script uses index.ios.js if it exists and is not empty, otherwise index.js. A project that renamed or moved its entry file gets no bundle.

ls index.js index.ios.js
grep -n "ENTRY_FILE" ios/*.xcodeproj/project.pbxproj

2Fix

Keep the entry file at the project root as index.js, or set ENTRY_FILE in the Bundle React Native code and images phase to the real path.

# in the build phase script, before the call to react-native-xcode.sh
export ENTRY_FILE=src/index.js

3Verify

Build Release again and confirm the bundle step ends without errors.

# Xcode: build the Release configuration; the bundle step finishes without errors

Confirmed by raw.githubusercontent.com

Did this fix it?

How do I stop it coming back?

  • Build the Release configuration on CI regularly, because debug builds on the Simulator skip bundling and hide this problem.
  • Keep ios/.xcode.env under version control and avoid machine-specific paths in it.
  • Run bundle exec pod install after every React Native upgrade.

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.