Build failing after pod install? Learn how to fix module not found, out-of-sync sandbox, and workspace errors so your CocoaPods dependencies link and compile in Xcode.
By far the most frequent reason CocoaPods dependencies fail to build is opening the .xcodeproj instead of the .xcworkspace. This mistake produces module not found and no such module errors.
CocoaPods integrates dependencies through the workspace, which links your app target with the Pods project. The bare project file knows nothing about the pods.
Close Xcode, then open the .xcworkspace file for your project. This single change resolves a surprising share of build failures.
If your imports resolve after switching, you have found your problem. Make it a habit to always open the workspace once CocoaPods is involved.
If you are already on the workspace but still see no such module for a pod, first confirm pod install actually completed successfully and that the library appears in the Pods project.
Do a clean build. In Xcode, clean the build folder, then build again, since stale build artifacts can hide a correctly installed pod.
Check that the pod is declared inside the correct target block in your Podfile. A library added to the wrong target will not be visible where you are importing it.
Also verify capitalization and the exact module name. The import name sometimes differs from the pod name, and the library's documentation lists the correct module to import.
The error stating the sandbox is not in sync with the Podfile.lock means Xcode's expectation of installed pods no longer matches what is actually on disk.
This commonly happens after pulling teammate changes, switching branches, or editing the Podfile without reinstalling. The manifest and the installed pods have diverged.
The fix is almost always to run pod install again from the project root. That re-synchronizes the installed pods with the current Podfile.lock and Manifest.lock.
After it completes, build again in the workspace. This error is really just CocoaPods telling you it needs to reconcile state, and pod install does exactly that.
When you pull changes and the build breaks, a teammate likely changed dependencies. Your local pods are now out of date relative to the committed Podfile.lock.
Run pod install to bring your installed pods in line with the lock file. Because the lock file is committed, this gives you the exact versions your teammate used.
If pod install itself reports problems, try updating your local copy of the pod specs repo, then run pod install again. Stale local spec metadata can prevent resolution.
This workflow is why committing the Podfile.lock matters so much. It is the shared source of truth that makes team dependency state reproducible.
Linker errors mentioning duplicate symbols often mean a library is being included twice, for example once via a pod and once manually, or the same dependency is pulled through two paths.
Audit your Podfile and your project for the library appearing more than once. Remove any manual copy that a pod now provides.
The use_frameworks! setting can also matter. Some libraries expect static linking and others dynamic, and mismatched expectations can surface as linker problems.
After adjusting, run pod install, clean the build folder, and rebuild. Linker issues are fiddly, so change one variable at a time and rebuild to isolate the cause.
Errors about a framework or header not found usually point at build setting drift, often after Xcode upgrades or manual changes to settings that CocoaPods manages.
CocoaPods writes its own configuration files, and if your target's configuration was overridden or detached, the pod search paths get lost. Check that your build configurations still reference the CocoaPods generated config files.
Re-running pod install regenerates these files and can reattach them. If a configuration was manually changed, you may need to restore it to inherit from the CocoaPods config.
As a reset, deleting the Pods directory and the workspace, then running pod install fresh, rebuilds the integration from scratch and clears accumulated cruft.
When multiple errors pile up and targeted fixes are not working, a full clean reinstall often clears the state. It is disruptive but reliable.
Delete the Pods directory and the generated .xcworkspace, clear Xcode's derived data, then run pod install to regenerate everything cleanly. Your Podfile and Podfile.lock remain the source of truth.
This rebuilds the entire integration and resolves problems caused by corrupted or half-applied earlier states. It is safe because nothing you delete here is irreplaceable.
After it finishes, open the fresh .xcworkspace and build. A clean reinstall resolves a large fraction of otherwise baffling CocoaPods build failures.
After an install or an Xcode upgrade, you may see warnings that some pods target an older deployment version than your app. These are usually warnings rather than hard failures, but they can turn into errors in strict configurations.
The platform line in your Podfile sets the baseline, so make sure it matches a deployment target your project genuinely supports. Aligning the two reduces mismatch noise.
Some teams add a post_install hook in the Podfile to normalize the deployment target across all pods. That is an advanced but common technique for taming these warnings at scale.
If a specific pod demands a newer minimum than your app supports, you will need to either raise your app's target or find a compatible version of that library. Read the pod's own documentation for its stated minimum.
Always open the workspace, always run pod install after changing the Podfile or pulling dependency changes, and always commit the Podfile.lock. These three habits prevent most issues.
Keep your CocoaPods version reasonably current, since old versions can conflict with newer Xcode releases. Toolchain mismatches are a recurring source of surprises.
When you upgrade Xcode, expect that a pod install and clean build may be needed to realign generated build settings.
And keep perspective: these are integration issues in the dependency layer. Your actual app is still native Swift or Objective-C built in Xcode, and shipping it still requires the Apple Developer Program.
When Xcode reports a module it should already see, stale build state is a common cause.
Start with Product then Clean Build Folder, which clears cached compiled artifacts. If the error persists, quit Xcode and delete the project derived data so the next build regenerates everything from scratch.
Confirm you opened the .xcworkspace rather than the .xcodeproj, since the workspace is what wires the Pods project into your targets.
If it still fails, a full reintegration often resolves it: run pod deintegrate, then pod install, and reopen the workspace. This rebuilds the CocoaPods integration cleanly and fixes cases where the generated configuration drifted out of sync with your project.
The most common cause is opening the .xcodeproj instead of the .xcworkspace. CocoaPods links dependencies through the workspace, so close Xcode and reopen the .xcworkspace. If that does not fix it, clean the build folder and confirm the pod is in the correct target.
It means the installed pods on disk no longer match what the Podfile.lock expects, usually after switching branches or editing the Podfile. Running pod install from the project root re-synchronizes them and clears the error.
A teammate likely changed dependencies. Run pod install to align your installed pods with the committed Podfile.lock, which gives you the exact versions they used. Update your local spec repo first if pod install reports resolution problems.
Try a clean reinstall: delete the Pods directory and generated .xcworkspace, clear Xcode derived data, then run pod install to regenerate everything. Your Podfile and Podfile.lock remain intact, so nothing important is lost.
Xcode upgrades can invalidate CocoaPods generated build settings. Re-run pod install and do a clean build to realign the configuration. Keeping CocoaPods reasonably up to date also reduces version conflicts with new Xcode releases.