Fix: Command PhaseScriptExecution failed with a nonzero exit code in Xcode

Why this happens

The Command PhaseScriptExecution failed with a nonzero exit code error is a critical build failure that occurs during the compilation process in Xcode. It indicates that a script defined in one of your project’s build phases—most often related to dependency management tools like CocoaPods—failed to execute successfully.

When using third-party libraries managed by CocoaPods, Xcode relies on specific build scripts to correctly link and bundle the necessary frameworks into the final application. If these scripts fail, or if the resulting frameworks are not correctly included in the final app bundle, the build process halts with this error.

This failure is frequently tied to missing configuration in the project settings, specifically regarding how the build system handles the inclusion of external frameworks, or sometimes due to corrupted build artifacts or keychain permissions.

How to fix it

Resolving this error requires a systematic approach, starting with the most likely configuration issues and moving toward general environment cleanup.

1. Verify Pods Framework Embedding (Most Likely Fix)

This is the most common cause when using CocoaPods. Xcode must be explicitly told to bundle the required frameworks from the Pods into your application target.

1. Open your project in Xcode and select your project file in the Project Navigator.
2. Select your main application Target.
3. Navigate to the Build Phases tab.
4. Locate the Embed Pods Framework phase. Ensure this phase is present and that the checkbox next to it is selected.
5. If you are using a very recent version of Xcode, this functionality may be listed under a different name, such as Bundle React Native code and images. Ensure the relevant embedding options are enabled.

2. Standard Xcode Cleanup

If the embedding phase is correct, the error might be due to stale build data or cached dependencies.

1. Clean the Build Folder: In Xcode, go to Product -> Clean Build Folder (or press Shift + Command + K).
2. Delete Derived Data: Close Xcode. Navigate to ~/Library/Developer/Xcode/DerivedData/ and delete the contents of this folder. This forces Xcode to rebuild all intermediate files from scratch.
3. Re-run the Build: Reopen your project and attempt to build again.

3. Reset Keychain Access and Permissions

In some instances, the build scripts rely on system-level permissions or cached credentials that may have become corrupted.

1. Open Keychain Access on your Mac.
2. In the sidebar, select Login.
3. Right-click on the Login entry and select Lock & Unlock (or use the equivalent system menu options to force a credential refresh).
4. After the system prompts you, restart Xcode and try building.

4. Reinstall Dependencies

If the issue persists, the dependency tree itself may be corrupted.

1. Navigate to your project directory in the Terminal.
2. Run pod deintegrate to remove existing CocoaPods installations.
3. Run pod install to reinstall all dependencies cleanly.
4. Open the newly generated .xcworkspace file and attempt to build.

How to prevent it

• Always use the .xcworkspace file when working with projects that utilize CocoaPods, never the .xcodeproj file.
• Regularly clean the build folder and delete Derived Data when encountering persistent build issues.
• Ensure your project targets have the necessary build phases (like ‘Embed Pods Framework’) correctly configured during initial setup.

FAQ

Why is my build failing during PhaseScriptExecution?

This error means a script defined in your build settings—often related to dependency management—failed to run successfully. It usually points to a configuration issue with how your project handles external libraries.

Does deleting Derived Data solve all build errors?

Deleting Derived Data is a powerful troubleshooting step for build issues, as it removes all cached intermediate files. While it resolves many problems, it is not a guaranteed fix for deep configuration errors.

How do I check if ‘Embed Pods Framework’ is enabled?

In Xcode, select your project, choose your Target, go to the Build Phases tab, and look for the ‘Embed Pods Framework’ entry under the ‘Dependencies’ or ‘Run Script’ sections.