XCODE TROUBLESHOOTING
Command PhaseScriptExecution Failed with a Nonzero Exit Code: How to Find and Fix the Real Xcode Error
This Xcode message is a summary, not the cause. Here is a dependable way to locate the failing Run Script phase and fix common CocoaPods, Flutter, React Native, permission, path, and configuration problems.
Quick answer
“Command PhaseScriptExecution failed with a nonzero exit code” means a shell script run by Xcode returned failure. The useful error is usually several lines above this message in the build log. Open the failing phase, find the first explicit error, then repair that script, tool, path, permission, or configuration.
What “Command PhaseScriptExecution” means in Xcode
An Xcode target can include several build phases. A Run Script phase executes shell commands during the build—for example, CocoaPods resource processing, Firebase configuration, SwiftLint checks, code generation, or a framework’s install script. Apple documents that these scripts run separately from compilation and linking phases.
A nonzero exit code is the standard shell signal for failure. It does not identify one universal problem, and deleting random build folders may only hide the evidence. The phase name and the first meaningful log line tell you what failed.
Command PhaseScriptExecution failed with a nonzero exit codeRead that as: “one command in a Run Script phase did not complete successfully.” The task is to find which command and why.
Step 1: Find the first actionable error in the build log
- Build again in Xcode so the log is current.
- Open Report navigator (the report icon in the left navigator).
- Select the failed build, expand the failed action, then expand the item named PhaseScriptExecution, Run Script, or a custom phase such as [CP] Embed Pods Frameworks.
- Search upward from the final red summary for the first line containing words such as
error:,command not found,Permission denied,No such file,Module not found, orCodeSign. - Copy that first error and the phase name. Those two lines are the useful bug report.
Do not troubleshoot from the last line alone. A script may print ten warnings and then fail because one required file, executable, environment variable, or signing input is missing. Apple also recommends using the build report logs to diagnose build failures.
Fast checklist before changing project files
- Confirm you opened the correct file: use the workspace (
.xcworkspace) when your project uses CocoaPods, not just the.xcodeproj. - Check the selected scheme, target, configuration (Debug/Release), and destination.
- Open Target → Build Phases and identify the exact failing script.
- Run the command shown in the log manually in Terminal only after reviewing what it does.
- Check whether a recently updated dependency changed Node, Ruby, CocoaPods, Flutter, Xcode, or macOS requirements.
- Clean only after recording the real error; then rebuild to confirm the cause is resolved.
Common PhaseScriptExecution causes and targeted fixes
1. The script cannot find a command
Typical log text: command not found: node, flutter, ruby, swiftlint, or bundle. Xcode does not always inherit the same PATH as your interactive Terminal, especially when a tool was installed through a version manager.
Fix the project’s documented toolchain first. Prefer an explicit, reproducible command or a project-managed version rather than adding a personal machine path to the repository. For example, a SwiftLint phase should call the binary path your team installs, and a Node-based script should use the project’s supported Node version.
2. Permission denied or a script is not executable
Typical log text: Permission denied or Operation not permitted. Check that the script exists, has the expected executable permission, and does not rely on a protected folder. For a repository script, the safe repair is often:
chmod +x path/to/script.shCommit the executable-bit change when it belongs to the project. Do not use broad permission changes such as chmod -R 777; they reduce security and rarely explain the root cause.
3. A file, generated config, or environment variable is missing
Typical log text: No such file or directory, unable to read, or an empty variable in a path. Verify the file path relative to $(PROJECT_DIR), confirm generated files are created before the consuming phase, and check Debug and Release separately. A local secret or configuration file that is intentionally ignored by Git still needs a documented setup step for every developer and CI machine.
4. CocoaPods integration is stale or incomplete
Errors from phases beginning with [CP] usually belong to CocoaPods. From the iOS directory, update pods according to your project’s supported Ruby and CocoaPods setup, then reopen the workspace:
cd ios
pod install
open Runner.xcworkspaceIf the log names a missing Pods file, first make sure Podfile, Podfile.lock, and the Pods state are consistent with the branch you checked out. Use pod repo update or a full pod reinstall only when the real log indicates dependency resolution or generated Pods files are the problem.
5. A script fails only in Archive or Release
Archive uses Release settings and can expose missing signing values, build variables, bundle resources, or configuration-specific files. Compare the failing target’s Build Settings in Debug and Release. Pay close attention to configuration files, build setting conditions, code signing, and scripts that expect a development-only path.
6. A dependency script no longer matches your toolchain
After upgrading Xcode, macOS, a plugin, CocoaPods, Node, or Ruby, an old script may break. Read the package’s release notes and the exact script output. Align versions deliberately; do not blindly downgrade Xcode or modify generated Pods scripts unless the dependency maintainer documents that workaround.
Flutter: fixing iOS PhaseScriptExecution errors
Flutter iOS builds commonly fail in Flutter’s build script or CocoaPods-generated phases. Start in the Flutter project root, then regenerate the iOS dependency state:
flutter clean
flutter pub get
cd ios
pod install
cd ..
flutter build ios --debugOpen ios/Runner.xcworkspace in Xcode for CocoaPods-based projects. If the error is still present, inspect the named phase:
- Thin Binary / Flutter build phase: verify the Flutter SDK path and the installed Flutter version; run
flutter doctor -vand resolve the actual reported issue. - [CP] Embed Pods Frameworks / Copy Pods Resources: run
pod install, then verify the workspace and Pods files match the branch. - Firebase or environment config: verify the required plist or generated configuration exists for the active scheme without committing secrets.
- Plugin-related error: update or pin the specific Flutter plugin only after confirming it supports your Flutter/Xcode version combination.
React Native: check Node, Pods, and generated scripts
For React Native projects, the phase may call Node, Hermes tooling, Metro-related scripts, or CocoaPods scripts. First identify the exact phase and missing executable. Then install dependencies with the project’s package manager and install pods from the iOS directory using the repository’s documented Ruby environment.
# Example only — use the package manager and version manager your project declares
package-manager install
cd ios
pod installWhen the log says node: command not found, solve the PATH/toolchain problem for Xcode rather than hard-coding a developer-specific Node location in a shared build phase.
Prevent future Run Script failures
- Give every script a clear name. “Generate API client” is easier to debug than an anonymous “Run Script.”
- Fail clearly. Print the tool version and the specific missing input before exiting; never print API keys, tokens, or certificates into build logs.
- Declare inputs and outputs. Apple’s build system uses them to schedule scripts correctly and avoid unnecessary repeated execution. Use
.xcfilelistfiles when the file set changes often. - Keep generated artifacts out of source folders. Apple recommends using
DERIVED_FILE_DIRfor intermediate script outputs. - Document setup. Pin or document Node, Ruby, CocoaPods, Flutter, and Xcode versions so local machines and CI run the same tools.
- Test a clean checkout in CI. This exposes undeclared local files, paths, and credentials before release day.
When cleaning Derived Data helps—and when it does not
Cleaning Derived Data can help after fixing a stale generated file, a changed dependency graph, or a corrupted intermediate artifact. It is not a primary diagnosis. If a script cannot find Node, lacks permission, references a missing file, or receives the wrong build setting, cleaning will not repair the underlying command.
Frequently asked questions
Is PhaseScriptExecution an Xcode bug?
Usually no. It is Xcode reporting that a configured script failed. The script may be yours, a dependency tool’s, or a generated CocoaPods phase.
What is the quickest fix?
Open the Report navigator and fix the first meaningful error above the final summary. The correct fix depends on that line; there is no safe one-command solution for every project.
Can I delete the Run Script phase?
Only if you understand its purpose and it is no longer required. Deleting a CocoaPods, code-generation, signing, or framework script can create a build that succeeds but crashes or breaks later.
Why does it work locally but fail in CI or Xcode Cloud?
CI starts from a cleaner, more restricted environment. Compare the Xcode version, dependency versions, environment variables, scripts, and required files. Never solve the difference by putting secrets in build logs.
Publish checklist for this article
- Use the suggested permalink and Blogger search description above.
- Add one original 1200 × 630 px or larger featured image; use the supplied alt text.
- Set the visible publication/update date and a real author or editorial identity.
- In the Blogger theme, use
max-image-preview:large, a canonical URL, and relevant Open Graph image tags. - Keep the page mobile-friendly, fast, and free from intrusive pop-ups. Google Discover eligibility is automatic for indexed, policy-compliant content; it cannot be guaranteed.
- Update the post when Xcode, Flutter, CocoaPods, or common build tooling changes.
