When Xcode shows “Command Ld failed with a nonzero exit code,” the linker has failed while creating the final app or executable. This line is usually only the final summary of the failure, so the most important step is to inspect the linker messages immediately above it.
- Causes
- Common situations
- How to check the error
- Fix 1: Add the missing framework or library
- Fix 2: Rebuild CocoaPods or Swift Package dependencies
- Fix 3: Remove duplicate links or source files
- Fix 4: Check Other Linker Flags
- Fix 5: Check architecture compatibility
- Fix 6: Clean the build and Derived Data
- Important notes
- Summary
Causes
Common causes include a missing framework or library, duplicate symbols, incompatible architectures, incorrect linker search paths, missing linker flags for a third-party library, or stale references left in Build Phases.
“Command Ld failed with a nonzero exit code” is a result message. The real cause is often shown a few lines earlier as “Undefined symbols,” “duplicate symbol,” “framework not found,” “library not found,” or another more specific linker error.
Common situations
- After adding, removing, or updating CocoaPods or Swift Package dependencies
- After manually adding or deleting a framework
- When integrating an Objective-C library into a Swift project
- When a binary supports a device architecture but not the Simulator, or vice versa
- After changing Target Membership or Build Phases
How to check the error
- Open Xcode’s Report navigator and select the failed build.
- Look above “Command Ld failed with a nonzero exit code.”
- Find the first specific linker error such as “Undefined symbols,” “duplicate symbol,” “framework not found,” or “library not found.”
- Check Target → Build Phases → Link Binary With Libraries.
- Check Library Search Paths, Framework Search Paths, and Other Linker Flags in Build Settings.
Fix 1: Add the missing framework or library
If a required framework is not linked, add it under Target → Build Phases → Link Binary With Libraries. For manually added libraries, also verify that the file exists and that the related search path is valid.
Fix 2: Rebuild CocoaPods or Swift Package dependencies
For CocoaPods, reinstall or update the dependencies and then reopen the workspace.
pod install
pod updateIf necessary, rebuild the Pods integration completely.
pod deintegrate
pod installFor Swift Package Manager, use Xcode’s package commands under File → Packages to resolve the dependencies again.
Fix 3: Remove duplicate links or source files
If the build log contains “duplicate symbol,” check whether the same source file or library is being included more than once. Review Compile Sources and Link Binary With Libraries in Build Phases.
Fix 4: Check Other Linker Flags
Some static Objective-C libraries require a linker flag such as:
-ObjCDo not add linker flags blindly. Follow the documentation for the SDK or library you are using, because unnecessary flags can create new linker problems.
Fix 5: Check architecture compatibility
A framework built only for iOS devices cannot always be linked into an iOS Simulator build, and the reverse is also true. Check Architectures, Excluded Architectures, and the supported platform slices in any XCFramework you use.
Fix 6: Clean the build and Derived Data
After correcting the configuration, run Product → Clean Build Folder. If stale build artifacts remain, remove Derived Data and rebuild.
rm -rf ~/Library/Developer/Xcode/DerivedData/*Important notes
Searching only for “Command Ld failed with a nonzero exit code” is less useful than reading the specific error immediately above it. That earlier message usually identifies the actual missing symbol, library, framework, or architecture.
Avoid adding random Library Search Paths or absolute paths just to make the build succeed locally. Those settings can break on CI or on another Mac.
Summary
“Command Ld failed with a nonzero exit code” means Xcode’s link stage failed. Start by reading the earlier linker messages, then check for missing frameworks or libraries, duplicate symbols, search paths, linker flags, and architecture mismatches. After fixing the configuration, clean the build folder or Derived Data if necessary.
