Fix: ld: framework not found Pods Linker Error in Xcode

Why this happens

The error ld: framework not found Pods (or ld: framework not found Pods_<TargetName>) occurs during the linking phase of an Xcode build. The clang linker is directed to link against CocoaPods artifacts, but the linker search paths either point to a missing directory or the framework target was never compiled.

The most frequent cause is opening the project using the standard .xcodeproj package instead of the .xcworkspace bundle generated by CocoaPods. A CocoaPods integration separates third-party dependencies into their own Xcode project (Pods.xcodeproj). When you open .xcodeproj directly, Xcode knows your main target expects a CocoaPods framework, but it has no build scheme or target reference to compile that dependency.

A secondary cause is stale or orphaned references in Xcode’s build settings. When upgrading CocoaPods, changing your Podfile configuration, or toggling use_frameworks!, earlier versions of CocoaPods or Xcode may leave behind an explicit reference to Pods.framework inside your target’s Frameworks, Libraries, and Embedded Content section. Because modern CocoaPods versions manage linking through .xcconfig files and target-specific frameworks (like Pods_YourApp.framework), an old static reference points to a nonexistent binary and causes ld to fail.

How to fix it

1. Open the .xcworkspace instead of the .xcodeproj

If you ran pod install and immediately launched your app via the original .xcodeproj file, CocoaPods targets cannot build alongside your app.

1. Quit Xcode completely (Cmd + Q).
2. Open your terminal or Finder and locate your project folder.
3. Verify that an .xcworkspace file exists in the directory.
4. Launch the project using the workspace file:

open YourProject.xcworkspace

5. Select your app scheme from the scheme selector toolbar.
6. Clean the build folder using Product > Clean Build Folder (Cmd + Shift + K), then build with Cmd + B.

2. Remove orphaned Pods framework references from build settings

If you are already inside the workspace and still encounter the error, Xcode may be attempting to link a deprecated, non-existent Pods.framework file.

1. Open your project in Xcode.
2. In the Project Navigator (left sidebar), select your root project node.
3. Select your app target under Targets.
4. Switch to the General tab.
5. Scroll down to Frameworks, Libraries, and Embedded Content.
6. Look for an entry named Pods.framework or Pods_YourApp.framework that shows a red icon or generic document icon indicating a missing path.
7. Select that item and click the minus (-) button to remove it.
8. Next, switch to the Build Phases tab.
9. Expand Link Binary With Libraries.
10. Check if Pods.framework is still listed there. If so, select it and click the minus (-) button.
11. Look at your Project Navigator file tree. If a group named Frameworks or Pods contains a red Pods.framework file, right-click it, select Delete, and choose Remove Reference.

After removing these references, clean your build folder (Cmd + Shift + K) and rebuild.

3. Verify target configurations in Project Info

CocoaPods injects build settings through .xcconfig files linked to your project configurations. If these links break, the linker will not know where CocoaPods outputs built frameworks.

1. In the Project Navigator, select the root project icon.
2. Under the Project section (above Targets), select your project.
3. Select the Info tab.
4. Expand the Configurations tree (Debug, Release, etc.).
5. Expand each target under your configurations.
6. Confirm that the Based on Configuration File column references Pods-YourApp.debug and Pods-YourApp.release respectively.

If any target says None, set it back to the corresponding CocoaPods configuration file or run the reset procedure in step 4 below.

4. Rebuild CocoaPods artifacts from scratch

If cached DerivedData or corrupted CocoaPods metadata prevent the linker from resolving the framework, perform a complete deintegration and clean reinstall.

1. Close Xcode.
2. Open Terminal and navigate to your project directory:

cd /path/to/YourProject

3. Remove the existing CocoaPods installation and cache:

pod deintegrate
rm -rf Pods
rm -rf YourProject.xcworkspace
rm -f Podfile.lock

4. Reinstall your dependencies:

pod install

5. Clear Xcode’s DerivedData folder to remove any cached index and intermediate build products:

rm -rf ~/Library/Developer/Xcode/DerivedData

6. Open the newly generated .xcworkspace file:

open YourProject.xcworkspace

7. Clean the build folder (Cmd + Shift + K) and build your target (Cmd + B).

How to prevent it

• Always launch via .xcworkspace: Create an alias or script that launches the workspace rather than clicking files in Finder.
• Do not manually link Pods frameworks: Avoid dragging generated Pods.framework files into your target’s Frameworks, Libraries, and Embedded Content manually. CocoaPods handles linking via xcconfig build settings and CocoaPods-generated build phase scripts.
• Re-run pod install after branch switches: When checking out Git branches with different dependencies or configuration changes, run pod install before compiling.
• Commit Podfile.lock: Always commit your Podfile.lock to source control so team members and CI pipelines resolve the exact same framework versions.

FAQ

Why does Pods.framework show up in red in my Project Navigator?

A red file name in Xcode indicates that the project file contains a path reference to a file that does not exist on disk. This commonly happens after modifying Podfile settings or clearing build artifacts while leaving manual framework references intact.

Does this error occur when using Swift Package Manager instead of CocoaPods?

No. Swift Package Manager (SPM) is integrated directly into Xcode’s project structure and does not create an external Pods.framework. However, if you recently migrated from CocoaPods to SPM, old CocoaPods build phases and manual framework links left behind in your project target will trigger this exact error.

Can running Xcode under Rosetta trigger this linker failure?

Running Xcode under Rosetta itself will not cause ld: framework not found Pods, but architecture mismatches can. If your Pods project is configured to exclude arm64 for simulators while your main app target includes it, the linker will look for an architecture-specific slice of the CocoaPods framework and fail to find the binary.